MediaMath
MediaMath Segment Groups API

Segment Groups
Documentation GitHub OpenAPI
OpenAPI Specification

openapi: 3.0.0
info:
  title: Campaigns Ad Servers Segment Groups API
  description: 'MediaMath Campaign Management API


    [Postman Collection](https://apidocs.mediamath.com/guides/postman-collections)

    '
  version: 3.0.1807
  contact:
    url: https://support.infillion.com/
servers:
- url: https://api.mediamath.com/api/v3.0
  description: Live Server
security:
- Auth0:
  - offline_access
  - manage:services
tags:
- name: Segment Groups
  description: Segment Groups
paths:
  /segment_groups:
    post:
      operationId: create-segment-group
      summary: Create a Segment Group
      description: Create a segment group
      tags:
      - Segment Groups
      requestBody:
        $ref: '#/components/requestBodies/segment_group_create'
      responses:
        '201':
          $ref: '#/components/responses/segment_group'
        '400':
          $ref: '#/components/responses/error'
        '401':
          $ref: '#/components/responses/error'
        '403':
          $ref: '#/components/responses/error'
        '404':
          $ref: '#/components/responses/error'
    get:
      operationId: list-segment-groups
      summary: List Segment Groups
      description: Get a list of segment groups
      tags:
      - Segment Groups
      parameters:
      - $ref: '#/components/parameters/page_limit'
      - $ref: '#/components/parameters/page_offset'
      - $ref: '#/components/parameters/sort_by'
      - $ref: '#/components/parameters/q'
      - $ref: '#/components/parameters/extended'
      - in: query
        name: currency_code
        schema:
          type: string
          example: USD
          minLength: 3
          maxLength: 3
        required: false
        description: "Optional currency code to return segment group members in a specific currency.\nIf not provided or not found, the default currency (USD) will be used.   \n"
      responses:
        '200':
          $ref: '#/components/responses/segment_group_collection'
        '400':
          $ref: '#/components/responses/error'
        '401':
          $ref: '#/components/responses/error'
        '403':
          $ref: '#/components/responses/error'
  /segment_groups/{segment_group_id}:
    post:
      operationId: update-segment-group
      summary: Update a Segment Group
      description: Update a segment group by ID
      parameters:
      - in: path
        name: segment_group_id
        schema:
          type: integer
        required: true
        description: Numeric ID of the segment group to update
      tags:
      - Segment Groups
      requestBody:
        $ref: '#/components/requestBodies/segment_group_update'
      responses:
        '200':
          $ref: '#/components/responses/segment_group'
        '400':
          $ref: '#/components/responses/error'
        '401':
          $ref: '#/components/responses/error'
        '403':
          $ref: '#/components/responses/error'
        '404':
          $ref: '#/components/responses/error'
    get:
      operationId: get-segment-group
      summary: Get a Segment Group
      description: Get a segment group by ID
      parameters:
      - $ref: '#/components/parameters/extended'
      - in: query
        name: currency_code
        schema:
          type: string
          example: USD
          minLength: 3
          maxLength: 3
        required: false
        description: "Optional currency code to return segment group members in a specific currency.\nIf not provided or not found, the default currency (USD) will be used.          \n"
      - in: path
        name: segment_group_id
        schema:
          type: integer
        required: true
        description: Numeric ID of the segment group to retrieve
      tags:
      - Segment Groups
      responses:
        '200':
          $ref: '#/components/responses/segment_group_single_get'
        '400':
          $ref: '#/components/responses/error'
        '401':
          $ref: '#/components/responses/error'
        '403':
          $ref: '#/components/responses/error'
        '404':
          $ref: '#/components/responses/error'
  /segment_groups/{segment_group_id}/history:
    get:
      operationId: segment-groups-audit-log
      summary: Segment Groups Audit Log
      description: Get a list of changes to this segment group
      tags:
      - Segment Groups
      parameters:
      - $ref: '#/components/parameters/page_limit'
      - $ref: '#/components/parameters/page_offset'
      - in: path
        name: segment_group_id
        schema:
          type: integer
        required: true
        description: Numeric ID of the segment group
      responses:
        '200':
          $ref: '#/components/responses/audit_log'
        '400':
          $ref: '#/components/responses/error'
        '401':
          $ref: '#/components/responses/error'
        '403':
          $ref: '#/components/responses/error'
        '404':
          $ref: '#/components/responses/error'
  /segment_groups/{segment_group_id}/assignments:
    get:
      operationId: get-segment-group-assignments
      summary: Get Segment Group Assignments
      description: Get all assignments for a specific segment group
      parameters:
      - $ref: '#/components/parameters/page_limit'
      - $ref: '#/components/parameters/page_offset'
      - in: path
        name: segment_group_id
        schema:
          type: integer
        required: true
        description: Numeric ID of the segment group to retrieve assignments for
      tags:
      - Segment Groups
      responses:
        '200':
          $ref: '#/components/responses/segment_group_assignments'
        '400':
          $ref: '#/components/responses/error'
        '401':
          $ref: '#/components/responses/error'
        '403':
          $ref: '#/components/responses/error'
        '404':
          $ref: '#/components/responses/error'
components:
  schemas:
    error_response:
      title: error response
      type: object
      required:
      - errors
      - meta
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
              field:
                description: Optional when it is a schema error
                type: string
              message:
                type: string
        meta:
          type: object
          required:
          - status
          properties:
            status:
              type: string
    segment_group_create:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 256
        type:
          type: string
          enum:
          - CONTEXTUAL
          - AUDIENCE
        organization_id:
          type: integer
          format: int32
          example: 1234
        status:
          type: boolean
        segment_subgroup:
          type: array
          items:
            type: object
            properties:
              segment_operator:
                type: string
                enum:
                - AND
                - OR
              segment_members:
                type: array
                items:
                  type: object
                  required:
                  - segment_id
                  - segment_type
                  properties:
                    segment_id:
                      type: integer
                      format: int32
                      example: 6
                    segment_type:
                      type: string
                      enum:
                      - CONTEXTUAL
                      - 3P
            required:
            - segment_operator
            - segment_members
      required:
      - name
      - type
      - organization_id
      - status
      - segment_subgroup
    single_metadata:
      title: single_metadata
      type: object
      properties:
        status:
          type: string
          example: success
      required:
      - status
    list_metadata:
      title: pagination metadata
      type: object
      properties:
        status:
          type: string
          example: success
          description: The status of the response, indicating success or failure.
        count:
          type: integer
          example: 10
          description: The number of items returned in the current response.
        total_count:
          type: integer
          example: 100
          description: The total number of items available in the dataset.
        offset:
          type: integer
          example: 0
          description: The offset from the start of the dataset, used for pagination.
        next_page:
          type: string
          description: The URL to fetch the next page of results.
        prev_page:
          type: string
          description: The URL to fetch the previous page of results.
      required:
      - status
      - count
    segment_group_update:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 256
        type:
          type: string
          enum:
          - CONTEXTUAL
          - AUDIENCE
        organization_id:
          type: integer
          format: int32
          example: 1234
        status:
          type: boolean
        segment_subgroup:
          type: array
          items:
            type: object
            properties:
              segment_operator:
                type: string
                enum:
                - AND
                - OR
              segment_members:
                type: array
                items:
                  type: object
                  required:
                  - segment_id
                  - segment_type
                  properties:
                    segment_id:
                      type: integer
                      format: int32
                      example: 6
                    segment_type:
                      type: string
                      enum:
                      - CONTEXTUAL
                      - 3P
            required:
            - segment_operator
            - segment_members
  responses:
    segment_group:
      description: Audience group response
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: object
                properties:
                  name:
                    type: string
                    example: My Audience Group
                  type:
                    type: string
                    example: CONTEXTUAL
                  organization_id:
                    type: integer
                    example: 1234
                  status:
                    type: boolean
                    example: true
                  segment_subgroup:
                    type: array
                    items:
                      type: object
                      properties:
                        segment_operator:
                          type: string
                          example: AND
                        segment_members:
                          type: array
                          items:
                            type: object
                            properties:
                              segment_id:
                                type: integer
                                format: int32
                              segment_type:
                                type: string
                                enum:
                                - CONTEXTUAL
                                - 3P
              meta:
                $ref: '#/components/schemas/single_metadata'
    segment_group_single_get:
      description: Audience group response
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: object
                properties:
                  name:
                    type: string
                    example: My Audience Group
                  type:
                    type: string
                    example: CONTEXTUAL
                  organization_id:
                    type: integer
                    example: 1234
                  status:
                    type: boolean
                    example: true
                  segment_subgroup:
                    type: array
                    items:
                      type: object
                      properties:
                        segment_operator:
                          type: string
                          example: AND
                        segment_members:
                          type: array
                          items:
                            type: object
                            properties:
                              name:
                                type: string
                                example: My Audience Group
                              segment_id:
                                type: integer
                                example: 5678
                              segment_type:
                                type: string
                                example: CONTEXTUAL
                              full_path:
                                type: string
                                example: My Audience Group Parent - My Audience Group
                              objective:
                                type: string
                                example: Custom
                              cpm:
                                type: number
                                example: 0.5
                              code:
                                type: string
                                example: SEG123
                              uniques:
                                type: integer
                                example: 1500
              meta:
                $ref: '#/components/schemas/single_metadata'
    segment_group_collection:
      description: Audience group collection response
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                      example: 1234
                    name:
                      type: string
                      example: My Audience Group
                    type:
                      type: string
                      example: CONTEXTUAL
                    organization_id:
                      type: integer
                      example: 1234
                    status:
                      type: boolean
                      example: true
                    segment_subgroup:
                      type: array
                      items:
                        type: object
                        properties:
                          segment_operator:
                            type: string
                            example: AND
                          segment_members:
                            type: array
                            items:
                              type: object
                              properties:
                                name:
                                  type: string
                                  example: My Audience Group
                                segment_id:
                                  type: integer
                                  example: 5678
                                segment_type:
                                  type: string
                                  example: CONTEXTUAL
                                full_path:
                                  type: string
                                  example: My Audience Group Parent - My Audience Group
                                objective:
                                  type: string
                                  example: Custom
                                cpm:
                                  type: number
                                  example: 0.5
                                code:
                                  type: string
                                  example: SEG123
                                uniques:
                                  type: integer
                                  example: 1500
              meta:
                $ref: '#/components/schemas/list_metadata'
    error:
      description: Error response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error_response'
    audit_log:
      description: Audit log response
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: array
                nullable: true
                items:
                  type: object
                  properties:
                    action:
                      type: string
                    date:
                      type: string
                      format: date-time
                    fields:
                      type: array
                      items:
                        type: object
                        properties:
                          field_name:
                            type: string
                          old_value:
                            type: string
                          new_value:
                            type: string
                    user_name:
                      type: string
                    user_id:
                      type: integer
                    collection:
                      type: string
                    entity_id:
                      type: integer
                    tool_name:
                      type: string
              meta:
                $ref: '#/components/schemas/list_metadata'
    segment_group_assignments:
      description: Audience group assignments response
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                      example: 1234
                    strategy_id:
                      type: integer
                      example: 5678
                    strategy_name:
                      type: string
                      example: My Strategy
                    campaign_id:
                      type: integer
                      example: 91011
                    campaign_name:
                      type: string
                      example: My Campaign
                    advertiser_id:
                      type: integer
                      example: 121314
                    advertiser_name:
                      type: string
                      example: My Advertiser
                    agency_id:
                      type: integer
                      example: 151617
                    agency_name:
                      type: string
                      example: My Agency
              meta:
                $ref: '#/components/schemas/list_metadata'
  requestBodies:
    segment_group_create:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/segment_group_create'
    segment_group_update:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/segment_group_update'
  parameters:
    q:
      in: query
      name: q
      schema:
        type: string
      required: false
      description: "Query search for filtering. This parameter can be used to filter results based on various fields.\nSupported operators:\n- `==` - numeric equality or case-sensitive string identity, \n- `==(1,2,3)` - IN query (only works for integers),\n- `!=` - numeric inequality or case-sensitive string non-identity,\n- `=:` - case-insensitive match, allows substring using * wildcards,\n- `<` - less than,\n- `<=` - less than or equal to,\n- `>` - greater than,\n- `>=` - greater than or equal to.\nExamples: \n- `q=name=:{search}*` to find all results with names starting with {search}.\n- `q=status==true` to find all active entities.\n- `q=id>=1000` to find all entities with id greater than or equal to 1000.\n- `q=id==(1,2,3)` to find specific entities by ID.\n- `q=created_on>1999-02-02` or `q=created_on>1999-02-02T00:00:00Z` to find entities created later than date.\n- `q=id>5&status==true` to find all active entities with id greater than 5.\n"
    page_offset:
      in: query
      name: page_offset
      schema:
        type: integer
        minimum: 0
        maximum: 1000
        example: 0
      required: false
      description: Index of the first element in the collection to retrieve
    sort_by:
      in: query
      name: sort_by
      description: "The field to sort by. You can use any field name in ascending or descending order.\nFor ascending order, use the field name directly, e.g., `id`. \nFor descending order, prefix the field name with a hyphen (`-`), e.g., `-id`.\n"
      schema:
        type: string
        example: id, -id, name, -name
      required: false
    page_limit:
      in: query
      name: page_limit
      schema:
        type: integer
        minimum: 1
        maximum: 1000
        example: 100
      required: false
      description: Number of elements in the collection to retrieve
    extended:
      in: query
      name: extended
      schema:
        type: boolean
      required: false
      description: Get extended properties in response
  securitySchemes:
    Auth0:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.mediamath.com/authorize
          scopes:
            offline_access: for refresh tokens
            manage:services: normal access
          tokenUrl: https://auth.mediamath.com/oauth/token
          refreshUrl: https://auth.mediamath.com/authorize?scope=offline_access
x-tagGroups:
- name: Hierarchy
  tags:
  - Advertisers
  - Agencies
  - Campaign Plans
  - Campaigns
  - Campaigns Budget Flights
  - New Strategy Plans
  - Organizations
  - Strategies
  - Strategy Parameters
  - Strategy Templates
- name: Targeting
  tags:
  - Segment Groups
  - Targeting
  - Targeting Attachments
  - Targeting Segment Objectives
  - Targeting Segments
- name: Creatives
  tags:
  - Atomic Creatives
  - Concepts
  - Creatives
  - Pixel Bundles
  - Pixel Providers
- name: Vendors & Contracts
  tags:
  - Audience Vendors
  - Contracts
  - Marketplaces
  - Vendor Contracts
  - Vendors
- name: Users & Access
  tags:
  - Enterprise Controls
  - User Permissions
  - Users
- name: Reference Data
  tags:
  - Ad Servers
  - Currency Rates
  - General
  - Sidekick Usage Logs
  - Site Lists
  - Supply Sources
  - Timezones
  - Verticals
MediaMath Segment Groups API

Documentation

Specifications

Other Resources

OpenAPI Specification
