Mapp Marketing Cloud Segmentation API

openapi: 3.2.0
info:
  title: Mapp Engage public Segmentation API
  version: '1'
  description: 'Mapp Engage REST API (REST 2.0, incremental version v19). Assembled verbatim from the per-operation OpenAPI fragments Mapp publishes on each endpoint page of https://docs.mapp.com/apidocs/. The base URL is tenant-specific: take your Mapp Engage login host and append /api/rest/v19.'
  contact:
    name: Mapp Technical Support
    url: https://mapp.com/tech-support/
servers:
- url: /api/rest/v19
security:
- basicAuth: []
tags:
- name: Segmentation
paths:
  /segmentation/create:
    post:
      tags:
      - Segmentation
      summary: Create a selection plan
      description: 'Creates a new selection plan. The request body is a wrapper whose json field carries the raw plan JSON document as a string (escaped). The plan must contain at least name and nodes; validate it against schema first. Returns the new plan''s id.


        Example body

        {

        "json": "{\"name\":\"My plan\",\"timeZoneId\":\"Europe/Belgrade\",\"nodes\":[ ... ]}"

        }'
      operationId: create_5
      responses:
        '200':
          description: The new plan's id, e.g. {"id":"..."}.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SegmentationReference'
        '400':
          description: bad request
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SegmentationPayload'
        description: Wrapper carrying the raw plan JSON document as a string in its 'json' field.
  /segmentation/delete:
    delete:
      tags:
      - Segmentation
      summary: Delete a selection plan
      description: Permanently deletes a selection plan by ID. Irreversible. Selection Builder responds 204 No Content on success.
      operationId: delete_3
      parameters:
      - name: id
        in: query
        description: ID of the plan to delete (GUID).
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Plan deleted.
        '400':
          description: bad request
  /segmentation/find:
    post:
      tags:
      - Segmentation
      summary: Find selection plans
      description: 'Returns a paged list of selection plans (without node detail). Filter, sort and paging criteria are supplied in the request body; all fields are optional - send an empty body or {} to list with server defaults.


        Body fields (all optional):


        page - zero-based page index (default 0).


        size - page size (default: server page size).


        sort - array of "field,asc|desc"; the first entry is the primary key, the rest are tie-breakers. E.g. "overviewCount.size,desc", "createdOn,asc".


        name - case-insensitive substring match on plan name.


        status - exact status, e.g. draft or published.


        labels - label filter.


        id - substring match on plan id.


        selectionTermId - match on the published selection term id.


        createdByName - case-insensitive substring on the creator''s display name.


        createdBefore / updatedBefore / publishedBefore - ISO-8601 timestamp upper bounds.


        Example body

        {

        "page": 0,

        "size": 3,

        "sort": ["overviewCount.size,desc", "createdOn,asc"],

        "name": "544"

        }'
      operationId: find_2
      responses:
        '200':
          description: A paged list of matching plans (without node detail).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SegmentationSearchResult'
        '400':
          description: bad request
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SegmentationSearchRequest'
        description: Filter, sort and paging criteria. All fields optional - send {} for server defaults. See the operation description for the full field list.
  /segmentation/getCount:
    get:
      tags:
      - Segmentation
      summary: Get a segment count
      description: Returns segment count size for requested selection plan id.
      operationId: getCount
      parameters:
      - name: termId
        in: query
        description: ID of selection term user wants to get a count for.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Returned count result with last updated date
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SelectionCountResult'
            application/xml:
              schema:
                $ref: '#/components/schemas/SelectionCountResult'
        '400':
          description: Provided term ID is invalid, No term id found for specified ID, An unexpected backend error has occurred.
  /segmentation/get:
    get:
      tags:
      - Segmentation
      summary: Get a selection plan
      description: 'Returns a single selection plan by ID in FULL - every node with its complete selector configuration. This is the lossless read: the returned shape is exactly what update accepts, so a fetch-modify-resubmit round-trip is safe. Use this (not preview) whenever the plan will be edited and saved back.'
      operationId: get_2
      parameters:
      - name: id
        in: query
        description: ID of the plan to retrieve (GUID), e.g. FF784C2A-B3FD-4851-A49A-ECC807E8F8A2.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The full plan as a JSON document.
          content:
            application/json:
              schema:
                type: string
        '400':
          description: bad request
  /segmentation/schema:
    get:
      tags:
      - Segmentation
      summary: Get the selection plan schema
      description: Returns the selection plan JSON schema as a string. The schema describes every node type, selector and field (including the string-boolean fields such as negated, caseSensitive, present and ignoreYear, which are serialized as the strings "true"/"false"). Fetch it once and validate a plan body against it before calling create or update. Takes no parameters.
      operationId: schema
      responses:
        '200':
          description: The schema as a JSON document string.
          content:
            application/json:
              schema:
                type: string
        '400':
          description: bad request
  /segmentation/preview:
    get:
      tags:
      - Segmentation
      summary: Preview a selection plan
      description: 'Returns a single selection plan by ID in REDUCED form: identity, status, time zone and a lightweight node tree (node types, and per criterion selector type / operator / property / values) but no selector configuration. Cheap to render and reason over. Lossy - never feed this back into update; use get for round-trips.'
      operationId: preview
      parameters:
      - name: id
        in: query
        description: ID of the plan to preview (GUID), e.g. FF784C2A-B3FD-4851-A49A-ECC807E8F8A2.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The reduced plan view as a JSON document.
          content:
            application/json:
              schema:
                type: string
        '400':
          description: bad request
  /segmentation/publish:
    post:
      tags:
      - Segmentation
      summary: Publish a selection plan
      description: Publishes a selection plan by ID, making it the live published version and assigning a selection term id. There is no request body - publishing acts on the plan already saved by create/update. The plan is fully validated on publish (drafts may save with invalid criteria, but publish rejects them). Returns the published plan's metadata (without node detail).
      operationId: publish
      parameters:
      - name: id
        in: query
        description: ID of the plan to publish (GUID).
        required: true
        schema:
          type: string
      - name: isBeta
        in: query
        description: Use the beta calculation path. Defaults to false.
        required: false
        schema:
          type: boolean
      - name: fastCountMode
        in: query
        description: Fast-count mode. Defaults to 'off'.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: The published plan's metadata (without node detail).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SegmentationInfo'
        '400':
          description: bad request
  /segmentation/triggerCount:
    post:
      tags:
      - Segmentation
      summary: Trigger a segment count
      description: Returns count size for requested termId.
      operationId: triggerCount
      parameters:
      - name: termId
        in: query
        description: ID of selection term user wants to get a count for.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Returns uuid of order for submitted termId
          content:
            application/json:
              schema:
                type: string
            application/xml:
              schema:
                type: string
        '400':
          description: Provided term ID is invalid, No term id found for specified ID, An unexpected backend error has occurred.
  /segmentation/update:
    put:
      tags:
      - Segmentation
      summary: Update a selection plan
      description: 'Overwrites an existing selection plan. The query parameter id identifies the plan; the request body is a wrapper whose json field carries the full plan JSON document as a string (escaped). Update replaces the whole plan, so fetch the current plan with get first, modify it, then send it back here. If the plan JSON also contains an id it must match the query id. Returns the updated plan.


        Example body

        {

        "json": "{\"id\":\"FF784C2A-...\",\"name\":\"My plan\",\"nodes\":[ ... ]}"

        }'
      operationId: update_5
      parameters:
      - name: id
        in: query
        description: ID of the plan to update (GUID).
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The updated plan as a JSON document.
          content:
            application/json:
              schema:
                type: string
        '400':
          description: bad request
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SegmentationPayload'
        description: Wrapper carrying the full plan JSON document as a string in its 'json' field.
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic authentication with a Mapp Engage system user of type API (or Hybrid).
x-apievangelist-provenance:
  method: searched
  generated: '2026-08-12'
  source: https://docs.mapp.com/apidocs/ (per-endpoint OpenAPI fragments)
  note: Union of the OpenAPI JSON fragments Mapp publishes on each endpoint page. Mapp does not serve one consolidated document at a public URL; the tenant-served Swagger lives at https://<your-engage-host>/apidoc/swagger.json and requires a tenant. Operation bodies, parameters, responses, tags, summaries and descriptions are verbatim from Mapp. The swagger/basePath/schemes/securityDefinitions envelope is added by API Evangelist from the published Getting Started guide; no operation content was authored.
  duplicate_operation_ids_suffixed: 30