News Break Ad Set API

openapi: 3.2.0
info:
  title: NewsBreak Advertising Ad Set API
  version: v1
  description: 'The NewsBreak Advertising API (NewsBreak API for Business) lets technology companies, direct advertisers and agencies programmatically manage the NewsBreak Ads Manager at scale: create and manage organizations, ad accounts and ad-account users; build campaigns, ad sets and ads; upload creative assets to the NewsBreak CDN; configure audience targeting and inventory platforms; manage account spending caps; read conversion tracking events; and run multidimensional performance reports.


    This document was generated by API Evangelist from the operations NewsBreak publishes in its Ad Manager API reference (https://advertising-api.newsbreak.com/hc/en-us). NewsBreak does not publish a machine-readable OpenAPI definition; every path, method, parameter, enumeration and response field here is transcribed from the published reference articles, which are linked per operation via externalDocs.'
  termsOfService: https://www.newsbreak.com/terms
  contact:
    name: NewsBreak Ad Support
    email: adsupport@newsbreak.com
    url: https://advertising-api.newsbreak.com/hc/en-us
servers:
- url: https://business.newsbreak.com/business-api/v1
  description: NewsBreak Advertising API production
security:
- AccessToken: []
tags:
- name: Ad Set
  description: 'Ad sets: budget, bidding, schedule, platforms and audience targeting.'
paths:
  /ad-set/create:
    post:
      operationId: createAdSet
      tags:
      - Ad Set
      summary: Create an ad set
      description: Create an ad set under a campaign, including budget, bidding, schedule and targeting.
      externalDocs:
        description: 'NewsBreak reference: Create an Ad Set'
        url: https://advertising-api.newsbreak.com/hc/en-us/articles/37869216635789-Create-an-Ad-Set
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAdSetRequest'
      responses:
        '200':
          description: 'Successful response. Check `code` in the body: 0 is success, any other value is an error (see Return Codes).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdSetResponse'
        '400':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '403':
          description: Permission denied, not logged in, invalid access token, or rate limit exceeded (return codes 403 / 4031 / 4033 / 4034).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /ad-set/getList:
    get:
      operationId: getAdSets
      tags:
      - Ad Set
      summary: Get ad sets
      description: Get all ad sets for an ad account. Optionally filter by search text, status or campaign.
      externalDocs:
        description: 'NewsBreak reference: Get Ad Sets'
        url: https://advertising-api.newsbreak.com/hc/en-us/articles/37869226813965-Get-Ad-Sets
      parameters:
      - name: adAccountId
        in: query
        required: true
        description: ID of ad account.
        schema:
          type: string
      - name: search
        in: query
        required: false
        description: Query to search.
        schema:
          type: string
      - name: onlineStatus
        in: query
        required: false
        description: Ad set status filter.
        schema:
          type: array
          items:
            type: string
            enum:
            - WARNING
            - INACTIVE
            - ACTIVE
            - DELETED
            - READY
            - COMPLETED
      - name: campaignIds
        in: query
        required: false
        description: Get ad sets in the given campaigns only.
        schema:
          type: array
          items:
            type: string
      - name: pageNo
        in: query
        required: true
        description: Page number.
        schema:
          type: integer
      - name: pageSize
        in: query
        required: true
        description: Page size.
        schema:
          type: integer
          enum:
          - 5
          - 10
          - 20
          - 50
          - 100
          - 200
          - 500
      responses:
        '200':
          description: 'Successful response. Check `code` in the body: 0 is success, any other value is an error (see Return Codes).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdSetPageResponse'
        '400':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '403':
          description: Permission denied, not logged in, invalid access token, or rate limit exceeded (return codes 403 / 4031 / 4033 / 4034).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /ad-set/update/{adSetId}:
    put:
      operationId: updateAdSet
      tags:
      - Ad Set
      summary: Update an ad set
      description: Update an ad set. All body fields are optional; only supplied fields are changed.
      externalDocs:
        description: 'NewsBreak reference: Update An Ad Set'
        url: https://advertising-api.newsbreak.com/hc/en-us/articles/37869314889229-Update-An-Ad-Set
      parameters:
      - name: adSetId
        in: path
        required: true
        description: ID of the ad set to update.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAdSetRequest'
      responses:
        '200':
          description: 'Successful response. Check `code` in the body: 0 is success, any other value is an error (see Return Codes).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdSetResponse'
        '400':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '403':
          description: Permission denied, not logged in, invalid access token, or rate limit exceeded (return codes 403 / 4031 / 4033 / 4034).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /ad-set/updateStatus/{adSetId}:
    put:
      operationId: updateAdSetStatus
      tags:
      - Ad Set
      summary: Update ad set status (ON/OFF)
      description: Enable or disable an ad set.
      externalDocs:
        description: 'NewsBreak reference: Update Ad Set Status (ON/OFF)'
        url: https://advertising-api.newsbreak.com/hc/en-us/articles/37869247409677-Update-Ad-Set-Status-ON-OFF
      parameters:
      - name: adSetId
        in: path
        required: true
        description: ID of the ad set to update.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StatusRequest'
      responses:
        '200':
          description: 'Successful response. Check `code` in the body: 0 is success, any other value is an error (see Return Codes).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdSetResponse'
        '400':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '403':
          description: Permission denied, not logged in, invalid access token, or rate limit exceeded (return codes 403 / 4031 / 4033 / 4034).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /ad-set/delete/{adSetId}:
    delete:
      operationId: deleteAdSet
      tags:
      - Ad Set
      summary: Delete an ad set
      description: Delete an ad set.
      externalDocs:
        description: 'NewsBreak reference: Delete an Ad Set'
        url: https://advertising-api.newsbreak.com/hc/en-us/articles/37869211527949-Delete-an-Ad-Set
      parameters:
      - name: adSetId
        in: path
        required: true
        description: ID of the ad set to delete.
        schema:
          type: string
      responses:
        '200':
          description: 'Successful response. Check `code` in the body: 0 is success, any other value is an error (see Return Codes).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdSetResponse'
        '400':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '403':
          description: Permission denied, not logged in, invalid access token, or rate limit exceeded (return codes 403 / 4031 / 4033 / 4034).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
components:
  schemas:
    StatusRequest:
      type: object
      description: Toggle the ON/OFF status of a campaign, ad set or ad.
      properties:
        status:
          type: string
          description: Target status.
          enum:
          - 'ON'
          - 'OFF'
      required:
      - status
    Targeting:
      type: object
      description: Audience targeting for an ad set. Each field accepts an AdSetTarget object with positive (include) and/or negative (exclude) lists. Mixing positive and negative is only allowed on location and device-location fields.
      additionalProperties:
        $ref: '#/components/schemas/TargetingField'
    UpdateAdSetRequest:
      type: object
      description: Ad set fields to update. All fields are optional; only supplied fields are changed.
      properties:
        name:
          type: string
          description: Descriptive name of the ad set.
        googlePlayId:
          type: string
          description: Package name of an Android app, e.g. com.particlenews.newsbreak. Required only for ad sets of an APP_TRAFFIC campaign.
        iosAppId:
          type: string
          description: Apple App Store URL, formatted http://apps.apple.com/<country>/app/<app-name>/id<store-ID>. Required only for ad sets of an APP_TRAFFIC campaign.
        budgetType:
          type: string
          description: Budget type of the ad set.
          enum:
          - DAILY
          - TOTAL
        budget:
          type: integer
          description: Budget of the ad set in cents.
        startTime:
          type: integer
          description: Start timestamp of the ad set.
        endTime:
          type: integer
          description: End timestamp of the ad set.
        bidType:
          type: string
          description: Bid type of the ad set.
          enum:
          - CPM
          - CPC
          - DAY_ONE_MAX_CONVERSION_VALUE
          - MAX_CONVERSION
          - MAX_CONVERSION_VALUE
          - TARGET_CPA
          - TARGET_ROAS
          - DAY_ONE_TARGET_ROAS
        schedule:
          type: object
          description: 'Schedule of the ad set: a map of week day (0 = Sunday) to hours 0-23.'
          additionalProperties:
            type: array
            items:
              type: integer
        bidRate:
          type: integer
          description: Bid rate of the ad set in cents. Required only when bidType is CPM, CPC or TARGET_CPA.
        roas:
          type: number
          format: double
          description: ROAS of the ad set. Required only when bidType is TARGET_ROAS or DAY_ONE_TARGET_ROAS.
        deliveryRate:
          type: string
          description: Delivery pacing. Required only when bidType is CPM or CPC; defaults to ASAP.
          enum:
          - EVENLY
          - ASAP
        trackingId:
          type: string
          description: Event tracking ID, from getEvents.
        platforms:
          type: array
          description: Inventory platforms. Defaults to ["APP_AND_WEB_UNLIMITED"], which must appear alone. At most one PREMIUM_PARTNERS_* value may appear. Duplicates are rejected.
          items:
            type: string
            enum:
            - APP_AND_WEB_UNLIMITED
            - NEWSBREAK
            - SCOOPZ
            - PREMIUM_PARTNERS_ALL
            - PREMIUM_PARTNERS_GAMING
            - PREMIUM_PARTNERS_NON_GAMING
        targeting:
          $ref: '#/components/schemas/Targeting'
    AdSetResponse:
      type: object
      description: Envelope carrying a single ad set.
      properties:
        code:
          type: integer
          description: Status code. 0 is successful; see Return Codes.
        errMsg:
          type: string
          description: Error message when code != 0.
        data:
          $ref: '#/components/schemas/AdSet'
    AdSetPageResponse:
      type: object
      description: Envelope carrying a page of ad sets.
      properties:
        code:
          type: integer
          description: Status code. 0 is successful; see Return Codes.
        errMsg:
          type: string
          description: Error message when code != 0.
        data:
          type: object
          properties:
            pageNo:
              type: integer
              description: Number of current page.
            pageSize:
              type: integer
              description: Size of current page.
            total:
              type: integer
              description: Total size for this search.
            hasNext:
              type: boolean
              description: Whether there is a next page.
            rows:
              type: array
              items:
                $ref: '#/components/schemas/AdSet'
    CreateAdSetRequest:
      type: object
      properties:
        campaignId:
          type: string
          description: ID of campaign.
        name:
          type: string
          description: Descriptive name of the ad set.
        googlePlayId:
          type: string
          description: Package name of an Android app, e.g. com.particlenews.newsbreak. Required only for ad sets of an APP_TRAFFIC campaign.
        iosAppId:
          type: string
          description: Apple App Store URL, formatted http://apps.apple.com/<country>/app/<app-name>/id<store-ID>. Required only for ad sets of an APP_TRAFFIC campaign.
        budgetType:
          type: string
          description: Budget type of the ad set.
          enum:
          - DAILY
          - TOTAL
        budget:
          type: integer
          description: Budget of the ad set in cents.
        startTime:
          type: integer
          description: Start timestamp of the ad set.
        endTime:
          type: integer
          description: End timestamp of the ad set.
        bidType:
          type: string
          description: Bid type of the ad set.
          enum:
          - CPM
          - CPC
          - DAY_ONE_MAX_CONVERSION_VALUE
          - MAX_CONVERSION
          - MAX_CONVERSION_VALUE
          - TARGET_CPA
          - TARGET_ROAS
          - DAY_ONE_TARGET_ROAS
        schedule:
          type: object
          description: 'Schedule of the ad set: a map of week day (0 = Sunday) to hours 0-23.'
          additionalProperties:
            type: array
            items:
              type: integer
        bidRate:
          type: integer
          description: Bid rate of the ad set in cents. Required only when bidType is CPM, CPC or TARGET_CPA.
        roas:
          type: number
          format: double
          description: ROAS of the ad set. Required only when bidType is TARGET_ROAS or DAY_ONE_TARGET_ROAS.
        deliveryRate:
          type: string
          description: Delivery pacing. Required only when bidType is CPM or CPC; defaults to ASAP.
          enum:
          - EVENLY
          - ASAP
        trackingId:
          type: string
          description: Event tracking ID, from getEvents.
        platforms:
          type: array
          description: Inventory platforms. Defaults to ["APP_AND_WEB_UNLIMITED"], which must appear alone. At most one PREMIUM_PARTNERS_* value may appear. Duplicates are rejected.
          items:
            type: string
            enum:
            - APP_AND_WEB_UNLIMITED
            - NEWSBREAK
            - SCOOPZ
            - PREMIUM_PARTNERS_ALL
            - PREMIUM_PARTNERS_GAMING
            - PREMIUM_PARTNERS_NON_GAMING
        targeting:
          $ref: '#/components/schemas/Targeting'
      required:
      - campaignId
      - name
      - budgetType
      - budget
      - startTime
      - endTime
      - bidType
    Envelope:
      type: object
      description: The standard NewsBreak response envelope. Every operation returns HTTP 200 with a `code` field; code 0 means success and any other value is an error (see Return Codes).
      properties:
        code:
          type: integer
          description: Status code. 0 is successful; see Return Codes.
        errMsg:
          type: string
          description: Error message when code != 0.
        data:
          type: object
          description: Response object.
    TargetingField:
      type: object
      description: An AdSetTarget object with positive (include) and/or negative (exclude) lists.
      properties:
        positive:
          type: array
          description: Values to include. Use ["all"] for unlimited; "all" may not be combined with other values.
          items:
            type: string
        negative:
          type: array
          description: Values to exclude. Only the location and device-location fields support a negative list.
          items:
            type: string
    AdSet:
      type: object
      description: 'An ad set: budget, bidding, schedule and targeting under a campaign.'
      properties:
        id:
          type: string
          description: Ad set ID.
        name:
          type: string
          description: Ad set name.
        orgId:
          type: string
          description: Organization ID.
        adAccountId:
          type: string
          description: Ad account ID.
        campaignId:
          type: string
          description: Campaign ID.
        trackingId:
          type: string
          description: Event tracking ID.
        budget:
          type: integer
          description: Ad set budget in cents.
        budgetType:
          type: string
          description: Budget type of the ad set.
          enum:
          - DAILY
          - TOTAL
        startTime:
          type: integer
          description: Start timestamp of the ad set.
        endTime:
          type: integer
          description: End timestamp of the ad set.
        bidType:
          type: string
          description: Bid type of the ad set.
          enum:
          - CPM
          - CPC
          - DAY_ONE_MAX_CONVERSION_VALUE
          - MAX_CONVERSION
          - MAX_CONVERSION_VALUE
          - TARGET_CPA
          - TARGET_ROAS
          - DAY_ONE_TARGET_ROAS
        bidRate:
          type: integer
          description: Bid rate of the ad set in cents.
        onlineStatus:
          type: string
          description: Online status of the ad set.
          enum:
          - WARNING
          - INACTIVE
          - ACTIVE
          - DELETED
          - READY
          - COMPLETED
        status:
          type: string
          description: Ad set status.
          enum:
          - 'ON'
          - 'OFF'
        targeting:
          $ref: '#/components/schemas/Targeting'
  securitySchemes:
    AccessToken:
      type: apiKey
      in: header
      name: Access-Token
      description: Authorized access token. Generate it in the NewsBreak Ad Manager under Resources -> API Access Tokens ("Generate Token"). The token carries the permissions granted by the advertiser. Keep it secret.
externalDocs:
  description: NewsBreak Ad Manager API reference
  url: https://advertising-api.newsbreak.com/hc/en-us