MediaMath Consumer Management API

openapi: 3.2.0
info:
  title: BOF Config Consumer Management API
  description: '1.'
  contact:
    url: https://apidocs.mediamath.com
    name: developers@mediamath.com
    email: developers@mediamath.com
  license:
    url: http://www.apache.org/licenses/LICENSE-2.0.html
    name: Apache 2.0
  version: '2.0'
servers:
- url: https://api.mediamath.com/opportunity-firehose/v2.0
tags:
- name: Consumer Management
  description: _
  x-internal: true
paths:
  /consumers:
    get:
      x-internal: true
      tags:
      - Consumer Management
      summary: Get list of accessible consumers
      description: 'Returns a list of the names of your consumers that you have access to.


        Sample endpoint: `https://api.mediamath.com/opportunity-firehose/v2.0/consumers`'
      operationId: list-accessible-customers
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
              examples:
                response:
                  value:
                    example-consumer: null
                    example-consumer-2: null
                    example-consumer-3: null
  /consumers/{name}/filters/{filter}:
    get:
      x-internal: true
      tags:
      - Consumer Management
      summary: Get a specific filter type
      description: 'This endpoint returns the filtered values within one of a consumer''s specified filter types


        Sample endpoint: `https://api.mediamath.com/opportunity-firehose/v2.0/consumers/example-consumer/filters/x-mm-channel-type`'
      operationId: list-filters-channel-types
      parameters:
      - name: filter
        in: path
        description: _
        required: true
        schema:
          type: string
      - name: name
        in: path
        description: _
        required: true
        schema:
          type: string
      responses:
        '200':
          description: "The schema is an array of elements from a filter type's accepted values list.  Many of these filter type value lists (everything except X-Mm-Deal-Id]) can be found on the home page of this document.  The filter types you may use include: \n```\nX-Mm-Geo\nX-Mm-Deal-Id \nX-Mm-Exch-Id\nX-Mm-Channel-Type \n```\n\nThe example below if for Channel Type."
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
              examples:
                response:
                  value:
                  - DISPLAY
                  - EMAIL
                  - MOBILE_DISPLAY_MOBILE_WEB
                  - MOBILE_VIDEO_MOBILE_WEB
                  - NEWSFEED
                  - SEARCH
                  - SOCIAL
                  - VIDEO
    post:
      x-internal: true
      tags:
      - Consumer Management
      summary: Post a specific filter type
      description: 'This endpoint lets you update filtered values under a given consumer''s specific filter type. Note: The user must have permission to add the filter value(s) to the filter (see the /permissions command).


        Sample POST endpoint: `https://api.mediamath.com/opportunity-firehose/v2.0/consumers/example-consumer/filter/x-mm-channel-type` with body `["DISPLAY","EMAIL"]`'
      operationId: Update-filters-channel-types
      parameters:
      - name: filter
        in: path
        description: _
        required: true
        schema:
          type: string
      - name: name
        in: path
        description: _
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema: {}
        description: "The schema is an array of elements from a filter type's accepted values list.  Many of these filter type value lists (everything except X-Mm-Deal-Id]) can be found on the home page of this document.  The filter types you may use include: \n```\nX-Mm-Geo\nX-Mm-Deal-Id \nX-Mm-Exch-Id\nX-Mm-Channel-Type \n```\n\nThe example below if for Channel Type."
      responses:
        '200':
          description: No response body, just the standard "200 OK" ACK to confirm acceptance of the new setting.
          content:
            application/json:
              schema:
                type: object
  /permissions:
    get:
      x-internal: true
      tags:
      - Consumer Management
      summary: Get permissions
      description: 'This endpoint returns the current lists of filters and parameters that you can update without having to engaging the MM team.


        If you would like to make updates to any other filters please email your account representative.


        Sample endpoint: `https://api.mediamath.com/opportunity-firehose/v2.0/permissions/`


        If you have access to:

        ```

        "EDIT.Filters.X-Mm-Exch-Id": [

        "15",

        "42",

        "62"

        ]

        ```

        This means that you can add or subtract thos exchange id values from any of your consumers you control as you see fit.'
      operationId: get-filter-list-per-consumer
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  AWSSettings.ASE256ServerSideEncryption:
                    type: object
                  AWSSettings.BucketPrefix:
                    type: object
                  AWSSettings.Buckets:
                    type: array
                    items:
                      type: string
                  AWSSettings.Regions:
                    type: array
                    items:
                      type: string
                  Endpoint.Consumers:
                    type: object
                  Endpoints.AWSSettings:
                    type: object
                  Endpoints.Config:
                    type: object
                  Endpoints.FilterPermissions:
                    type: object
                  Endpoints.Filters:
                    type: object
                  Endpoints.SampleSettings:
                    type: object
                  Endpoints.WebSettings:
                    type: object
                  Filters.X-Mm-Exch-Id:
                    type: array
                    items:
                      type: string
                  WebSettings.Endpoints:
                    type: array
                    items:
                      type: string
              examples:
                response:
                  value:
                    EDIT.AWSSettings.ASE256ServerSideEncryption: ALLOWED
                    EDIT.AWSSettings.BucketPrefix: ALLOWED
                    EDIT.AWSSettings.Buckets:
                    - ewr
                    - iad
                    - ord
                    - pao
                    - sjc
                    EDIT.AWSSettings.PartitionMacro: ALLOWED
                    EDIT.AWSSettings.Regions:
                    - ewr
                    - iad
                    - ord
                    - pao
                    - sjc
                    EDIT.DropBody: ALLOWED
                    EDIT.DropExchangeUID: ALLOWED
                    EDIT.DropZeroUID: ALLOWED
                    EDIT.Filters.X-Mm-Channel-Type:
                    - DISPLAY
                    - VIDEO
                    - SOCIAL
                    - MOBILE_DISPLAY_MOBILE_WEB
                    - MOBILE_VIDEO_MOBILE_WEB
                    - SEARCH
                    - EMAIL
                    - MOBILE_DISPLAY_IN_APP
                    - MOBILE_VIDEO_IN_APP
                    - NEWSFEED
                    EDIT.Filters.X-Mm-Exch-Id:
                    - '15'
                    - '42'
                    - '62'
                    - '63'
                    - '65'
                    - '66'
                    - '67'
                    - '69'
                    - '70'
                    - '71'
                    - '72'
                    - '73'
                    - '74'
                    - '75'
                    - '76'
                    - '82'
                    - '83'
                    - '87'
                    - '89'
                    - '91'
                    - '92'
                    - '94'
                    - '96'
                    EDIT.SampleSettings.Disabled: ALLOWED
                    EDIT.SampleSettings.SampleRate: ALLOWED
                    EDIT.WebSettings.Endpoints:
                    - ewr
                    - iad
                    - ord
                    - pao
                    - sjc
                    GET.ConsumerSettings: ALLOWED
                    GET.Consumers: ALLOWED
                    GET.Filters: ALLOWED
                    GET.Permissions: ALLOWED
                    GET.SampleSettings: ALLOWED
                    GET.WebSettings: ALLOWED
                    POST.ConsumerSettings: ALLOWED
                    POST.Filter: ALLOWED
                    POST.SampleSettings: ALLOWED
                    POST.WebSettings: ALLOWED
  /consumers/{name}/filters:
    get:
      x-internal: true
      tags:
      - Consumer Management
      summary: Get filters
      description: 'This endpoint returns all of the current filters you have for a specified consumer.


        For more information on other filters that MediaMath would have to change for you, checkout our other documentation.


        Sample endpoint: `https://api.mediamath.com/opportunity-firehose/v2.0/consumers/example-consumer/filters`'
      operationId: List-consumers-active-filters
      parameters:
      - name: name
        in: path
        description: Consumer name
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  X-Mm-Channel-Type:
                    type: array
                    items:
                      type: string
                  X-Mm-Exch-Id:
                    type: array
                    items:
                      type: string
                  X-Mm-Geo:
                    type: array
                    items:
                      type: string
              examples:
                response:
                  value:
                    X-Mm-Channel-Type:
                    - DISPLAY
                    - EMAIL
                    - MOBILE_DISPLAY_MOBILE_WEB
                    - MOBILE_VIDEO_MOBILE_WEB
                    - NEWSFEED
                    - SEARCH
                    - SOCIAL
                    - VIDEO
                    X-Mm-Exch-Id:
                    - '42'
                    - '62'
                    - '63'
                    - '65'
                    - '66'
                    - '67'
                    - '69'
                    - '70'
                    - '71'
                    - '72'
                    - '73'
                    - '74'
                    - '75'
                    - '76'
                    - '82'
                    - '83'
                    - '87'
                    - '89'
                    - '91'
                    - '92'
                    - '94'
                    - '96'
                    X-Mm-Geo:
                    - '60231'
  /consumers/{name}/samplesettings:
    get:
      x-internal: true
      tags:
      - Consumer Management
      summary: Get sample settings
      description: 'This will get your consumer''s current disable/enable and sample rate status.


        Sample endpoint: `https://api.mediamath.com/opportunity-firehose/v2.0/consumers/example-consumer/samplesettings`'
      operationId: Get-consumer-statuses
      parameters:
      - name: name
        in: path
        description: _
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  Disabled:
                    type: boolean
                  SampleRate:
                    type: integer
                    minimum: 1
                    maximum: 100
              examples:
                response:
                  value:
                    Disabled: false
                    SampleRate: 15
    post:
      x-internal: true
      tags:
      - Consumer Management
      summary: Post sample settings
      description: This will set your sample rate and/or disabled value.
      operationId: Set-consumer-statuses
      parameters:
      - name: name
        in: path
        description: _
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema: {}
        description: _
      responses:
        '200':
          description: No response body, just the standard "200 OK" ack to confirm acceptance of the new setting.
          content:
            application/json:
              schema:
                type: object
  /consumers/{name}:
    get:
      x-internal: true
      tags:
      - Consumer Management
      summary: Get consumer config
      description: 'Get details of a specific consumer (which includes but is not limited to the filters)


        Sample endpoint: `https://api.mediamath.com/opportunity-firehose/v2.0/consumers/example-consumer`'
      operationId: Get-consumer-details
      parameters:
      - name: name
        in: path
        description: _
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  Name:
                    type: string
                  DropZeroUID:
                    type: boolean
                  DropExchangeUID:
                    type: boolean
                  DropBody:
                    type: boolean
                  Filters:
                    type: object
                    properties:
                      X-Mm-Channel-Type:
                        type: array
                        items:
                          type: string
                          enum:
                          - DISPLAY
                          - EMAIL
                          - MOBILE_DISPLAY_IN_APP
                          - MOBILE_DISPLAY_MOBILE_WEB
                          - MOBILE_VIDEO_IN_APP
                          - MOBILE_VIDEO_MOBILE_WEB
                          - NEWSFEED
                          - SEARCH
                          - SOCIAL
                          - VIDEO
                      X-Mm-Exch-Id:
                        type: array
                        items:
                          type: string
                      X-Mm-Geo:
                        type: array
                        items:
                          type: string
                  SampleSettings:
                    type: object
                    properties:
                      Disabled:
                        type: boolean
                      SampleRate:
                        type: integer
                  WebSettings:
                    type: object
                    properties:
                      Endpoints:
                        type: object
                        properties:
                          ewr:
                            type: string
                            format: uri
                          ord:
                            type: string
                            format: uri
                          pao:
                            type: string
                            format: uri
                          ams:
                            type: string
                            format: uri
                          zrh:
                            type: string
                            format: uri
                          nrt:
                            type: string
                            format: uri
                          hkg:
                            type: string
                            format: uri
              examples:
                response:
                  value:
                    Name: example-consumer
                    DropZeroUID: true
                    DropExchangeUID: true
                    DropBody: false
                    Filters:
                      X-Mm-Channel-Type:
                      - DISPLAY
                      - EMAIL
                      - MOBILE_DISPLAY_MOBILE_WEB
                      - MOBILE_VIDEO_MOBILE_WEB
                      - NEWSFEED
                      - SEARCH
                      - SOCIAL
                      - VIDEO
                      X-Mm-Exch-Id:
                      - '15'
                      X-Mm-Geo:
                      - '60231'
                    SampleSettings:
                      Disabled: false
                      SampleRate: 15
                    WebSettings:
                      Endpoints:
                        ewr: https://example.com
                        ord: https://example.com
                        pao: https://example.com
    post:
      x-internal: true
      tags:
      - Consumer Management
      summary: Post consumer config
      description: This endpoint allows you to edit your entire config directly instead of in pieces as you see fit. You can take the output of /consumers/{name} and POST it back here and any changes will be updated
      operationId: post_consumer_config
      parameters:
      - name: name
        in: path
        description: _
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
              examples:
                response:
                  value:
                    DropZeroUID: false
                    DropExchangeUID: false
                    DropBody: false
                    Filters:
                      X-Mm-Exch-Id:
                      - '15'
                    SampleSettings:
                      Disabled: true
                      SampleRate: 1
                    AwsSettings:
                      Regions:
                        ewr: us-east-1
                        iad: us-east-1
                      Buckets:
                        ewr: example-bucket-name
                        iad: example-bucket-name
                      ASE256ServerSideEncryption: false
  /consumers/{name}/websettings:
    get:
      x-internal: true
      tags:
      - Consumer Management
      summary: Get consumer web settings
      description: 'This will get your consumer''s web settings.


        Sample endpoint: `https://api.mediamath.com/opportunity-firehose/v2.0/consumers/example-consumer/websettings`'
      operationId: list-consumer-websettings
      parameters:
      - name: name
        in: path
        description: _
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
              examples:
                response:
                  value:
                    Endpoints:
                      ewr: https://newlocations.com/
                      ord: https://newlocations.com/
    post:
      x-internal: true
      tags:
      - Consumer Management
      summary: Post consumer web settings
      description: This will set your consumer's web settings.
      operationId: set-consumer-websettings
      parameters:
      - name: name
        in: path
        description: _
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema: {}
        description: 'Viewer said

          Endpoints: map[string]string'
      responses:
        '200':
          description: There is no response beyond the 200 OK acknowledgment
          content:
            application/json:
              schema:
                type: object
              examples:
                response:
                  value:
                    Endpoints:
                      ewr: https://newlocations.com/
                      ord: https://newlocations.com/
  /consumers/{name}/awssettings:
    get:
      x-internal: true
      tags:
      - Consumer Management
      summary: Get consumer aws settings
      description: 'This will get your consumer''s awssettings.


        Sample endpoint: `https://api.mediamath.com/opportunity-firehose/v2.0/consumers/example-consumer/awssettings`'
      operationId: List-consumer-awsettings
      parameters:
      - name: name
        in: path
        description: _
        required: true
        schema:
          type: string
      responses:
        '200':
          description: "RoleARN = The Amazon Resource Name (ARN) of the role that the caller is assuming\n\nExternal ID = A unique identifier that is used by third parties to assume a role in their customers' accounts. For each role that the third party can assume, they should instruct their customers to create a role with the external ID that the third party generated. Each time the third party assumes the role, they must pass the customer's external ID. The external ID is useful in order to help third parties bind a role to the customer who created it.\n\nASE256ServerSideEncryption = Amazon's S3 256-bit Advanced Encryption Standard\n\t\t\t\t\t\t"
          content:
            application/json:
              schema:
                type: object
              examples:
                response:
                  value:
                    Regions:
                      ewr: us-east-1
                      iad: us-east-1
                    Buckets:
                      ewr: mm-lab-bof-dump
                      iad: mm-lab-bof-dump
                    ASE256ServerSideEncryption: false
    post:
      x-internal: true
      tags:
      - Consumer Management
      summary: Post consumer aws settings
      description: 'This will set your consumer''s awssettings.


        Note: "RoleARN" and "ExternalID" cannot be changed'
      operationId: set-consumer-awsettings
      parameters:
      - name: name
        in: path
        description: _
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema: {}
        description: "RoleARN = The Amazon Resource Name (ARN) of the role that the caller is assuming\n\nExternal ID = A unique identifier that is used by third parties to assume a role in their customers' accounts. For each role that the third party can assume, they should instruct their customers to create a role with the external ID that the third party generated. Each time the third party assumes the role, they must pass the customer's external ID. The external ID is useful in order to help third parties bind a role to the customer who created it.\n\nASE256ServerSideEncryption = Is Amazon S3 256-bit Advanced Encryption Standard used? (true or false)\n\t\t\t\t\t\t"
      responses:
        '200':
          description: "There is no response beyond the 200 OK acknowledgment\n\t"
          content:
            application/json:
              schema:
                type: object
              examples:
                response:
                  value:
                    Regions:
                      ewr: us-east-1
                      iad: us-east-1
                    Buckets:
                      ewr: mm-lab-bof-dump
                      iad: mm-lab-bof-dump
                    ASE256ServerSideEncryption: false
components:
  securitySchemes:
    oauth2:
      type: oauth2
      description: 'You will need an auth0 account with MediaMath to gain access to your consumer.


        Curl auth.mediamath.com with your client ID and secret


        `POST https://auth.mediamath.com/oauth/token`

        Example Request:

        `curl -X POST --header  ''content-type: application/json'' ''https://auth.mediamath.com/oauth/token'' -d ''{"audience": "https://api.mediamath.com/opportunity_firehose/", "grant_type":"client_credentials", "client_id":"{CLIENT_ID}", "client_secret":"{CLIENT_SECRET}"}''`

        Example Response:

        `{"access_token":"ACCESS_TOKEN_HERE","expires_in":86400,"token_type":"Bearer"}`

        Use this token here when sending requests to https://api.mediamath.com/opportunity-firehose/v2.0/


        `curl -X GET -H "Authorization:Bearer ACCESS_TOKEN_HERE" ''https://api.mediamath.com/opportunity-firehose/v2.0/''`'
      flows:
        password:
          tokenUrl: https:/auth.mediamath.com/oauth/token
          scopes: {}
    Cookie_auth:
      type: apiKey
      description: 'Cookie: adama_sesion=`cookie-id`'
      name: Cookie
      in: header