News Break Ad Account API

openapi: 3.2.0
info:
  title: NewsBreak Advertising Ad Account 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 Account
  description: Ad accounts under an organization and the users who can access them.
paths:
  /ad-account/create:
    post:
      operationId: createAdAccount
      tags:
      - Ad Account
      summary: Create an ad account
      description: Create an ad account under an organization.
      externalDocs:
        description: 'NewsBreak reference: Create An Ad Account'
        url: https://advertising-api.newsbreak.com/hc/en-us/articles/45689340192781-Create-An-Ad-Account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAdAccountRequest'
      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/AdAccountResponse'
        '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-account/getGroupsByOrgIds:
    get:
      operationId: getAdAccounts
      tags:
      - Ad Account
      summary: Get ad accounts
      description: Get all ad accounts' IDs and names for each organization, grouped by organization ID and name. Users only receive ad accounts they have access to.
      externalDocs:
        description: 'NewsBreak reference: Get Ad Accounts'
        url: https://advertising-api.newsbreak.com/hc/en-us/articles/37869173867789-Get-Ad-Accounts
      parameters:
      - name: orgIds
        in: query
        required: true
        description: IDs of organizations.
        schema:
          type: array
          items:
            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/AdAccountGroupsResponse'
        '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-account/addUser:
    post:
      operationId: addAdAccountUser
      tags:
      - Ad Account
      summary: Add a user to an ad account
      description: Grant a user access to an ad account under an organization. If the user does not yet exist, an account is created and an invitation email is sent. The user is also granted an organization-level membership role if they don't already have one.
      externalDocs:
        description: 'NewsBreak reference: Add a User to an Ad Account'
        url: https://advertising-api.newsbreak.com/hc/en-us/articles/46938559949069-Add-a-User-to-an-Ad-Account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddAdAccountUserRequest'
      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/Envelope'
        '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-account/deleteUser:
    post:
      operationId: deleteAdAccountUser
      tags:
      - Ad Account
      summary: Remove a user from an ad account
      description: Revoke a user's access to an ad account under an organization. This removes only the user's ad-account-level role; any organization-level role is left unchanged.
      externalDocs:
        description: 'NewsBreak reference: Remove a User from an Ad Account'
        url: https://advertising-api.newsbreak.com/hc/en-us/articles/46938642910477-Remove-a-User-from-an-Ad-Account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteAdAccountUserRequest'
      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/Envelope'
        '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:
    AdAccountGroupsResponse:
      type: object
      description: Envelope carrying ad accounts grouped by organization.
      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:
            list:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                    description: Organization ID.
                  name:
                    type: string
                    description: Organization name.
                  adAccounts:
                    type: array
                    items:
                      $ref: '#/components/schemas/AdAccount'
    CreateAdAccountRequest:
      type: object
      properties:
        adAccountName:
          type: string
          description: Descriptive name of the ad account. 1-256 characters.
        companyName:
          type: string
          description: Company name associated with the ad account. 1-1024 characters.
        industry:
          type: string
          description: Industry classification in the form <category>//<subcategory>, e.g. "Ad Safety Risk//Other". Must match a value from the published industry list.
        orgId:
          type: string
          description: ID of the organization the ad account belongs to.
      required:
      - adAccountName
      - companyName
      - industry
      - orgId
    DeleteAdAccountUserRequest:
      type: object
      properties:
        orgId:
          type: string
          description: ID of the organization the ad account belongs to.
        adAccountId:
          type: string
          description: ID of the ad account to revoke access from. Must belong to orgId.
        userId:
          type: string
          description: ID of the user whose ad-account access is being removed.
      required:
      - orgId
      - adAccountId
      - userId
    AdAccountResponse:
      type: object
      description: Envelope carrying a single ad account.
      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/AdAccount'
    AdAccount:
      type: object
      description: An ad account under an organization.
      properties:
        id:
          type: string
          description: Ad account ID.
        name:
          type: string
          description: Ad account name.
        orgId:
          type: string
          description: Organization ID.
        orgName:
          type: string
          description: Organization name.
        companyName:
          type: string
          description: Company name associated with the ad account.
        createTime:
          type: string
          description: Create time of the ad account.
    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.
    AddAdAccountUserRequest:
      type: object
      properties:
        orgId:
          type: string
          description: ID of the organization the ad account belongs to.
        adAccountId:
          type: string
          description: ID of the ad account to grant access to. Must belong to orgId.
        email:
          type: string
          description: Email address of the user to add.
        role:
          type: string
          description: Access role to assign on the ad account.
          enum:
          - ACC_ADMIN
          - ACC_OPERATOR
          - ACC_VIEWER
      required:
      - orgId
      - adAccountId
      - email
      - role
  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