openapi: 3.1.0 info: title: NewsBreak Advertising 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 externalDocs: description: NewsBreak Ad Manager API reference url: https://advertising-api.newsbreak.com/hc/en-us servers: - url: https://business.newsbreak.com/business-api/v1 description: NewsBreak Advertising API production tags: - name: Organization description: Organizations the calling user administers. - name: Ad Account description: Ad accounts under an organization and the users who can access them. - name: Campaign description: 'Campaigns: the objective-level container for ad sets.' - name: Ad Set description: 'Ad sets: budget, bidding, schedule, platforms and audience targeting.' - name: Ad description: Ads and their creatives, plus creative asset upload. - name: Report description: Synchronous and saved custom performance reports. - name: Account Billing description: Account-level spending caps and remaining budget. - name: Event Management description: Conversion tracking events (pixel and postback). security: - AccessToken: [] paths: /org/admin-orgs: get: operationId: getAdminOrgs tags: - Organization summary: Get org admin's organizations description: Get all organizations where the calling user holds the ORG_ADMIN role. The caller is identified by the access token — no request parameters are required. externalDocs: description: 'NewsBreak reference: Get Org Admin''s Organizations' url: https://advertising-api.newsbreak.com/hc/en-us/articles/45246356925965-Get-Org-Admin-s-Organizations 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/OrganizationListResponse' '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/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' /campaign/create: post: operationId: createCampaign tags: - Campaign summary: Create a campaign description: Create a campaign under an ad account. externalDocs: description: 'NewsBreak reference: Create a Campaign' url: https://advertising-api.newsbreak.com/hc/en-us/articles/37869159614477-Create-a-Campaign requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateCampaignRequest' 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/CampaignResponse' '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' /campaign/getList: get: operationId: getCampaigns tags: - Campaign summary: Get campaigns description: Get all campaigns for an ad account. Optionally filter to return only certain campaigns. externalDocs: description: 'NewsBreak reference: Get Campaigns' url: https://advertising-api.newsbreak.com/hc/en-us/articles/37869190998925-Get-Campaigns 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: Campaign status filter. schema: type: array items: type: string enum: - WARNING - INACTIVE - ACTIVE - DELETED - 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/CampaignPageResponse' '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' /campaign/update/{campaignId}: put: operationId: updateCampaign tags: - Campaign summary: Update a campaign description: Update a campaign. externalDocs: description: 'NewsBreak reference: Update a Campaign' url: https://advertising-api.newsbreak.com/hc/en-us/articles/37869170482061-Update-a-Campaign parameters: - name: campaignId in: path required: true description: ID of the campaign to update. schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateCampaignRequest' 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/CampaignResponse' '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' /campaign/updateStatus/{campaignId}: put: operationId: updateCampaignStatus tags: - Campaign summary: Update campaign status (ON/OFF) description: Enable or disable a campaign. externalDocs: description: 'NewsBreak reference: Update Campaign Status (ON/OFF)' url: https://advertising-api.newsbreak.com/hc/en-us/articles/37869222017549-Update-Campaign-Status-ON-OFF parameters: - name: campaignId in: path required: true description: ID of the campaign 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/CampaignResponse' '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' /campaign/delete/{campaignId}: delete: operationId: deleteCampaign tags: - Campaign summary: Delete a campaign description: Delete a campaign. The returned campaign has onlineStatus DELETED. externalDocs: description: 'NewsBreak reference: Delete a Campaign' url: https://advertising-api.newsbreak.com/hc/en-us/articles/37869167992077-Delete-a-Campaign parameters: - name: campaignId in: path required: true description: ID of the campaign 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/CampaignResponse' '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/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' /ad/create: post: operationId: createAd tags: - Ad summary: Create an ad description: Create an ad under an ad set, with its creative. Creative asset URLs must first be uploaded through uploadAdAssets. externalDocs: description: 'NewsBreak reference: Create an Ad' url: https://advertising-api.newsbreak.com/hc/en-us/articles/37869297161741-Create-an-Ad requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAdRequest' 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/AdResponse' '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/getList: get: operationId: getAds tags: - Ad summary: Get ads description: Get all ads for an ad account. Optionally filter by search text, status, campaign or ad set. externalDocs: description: 'NewsBreak reference: Get Ads' url: https://advertising-api.newsbreak.com/hc/en-us/articles/37869300764813-Get-Ads 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 status filter. schema: type: array items: type: string enum: - WARNING - INACTIVE - ACTIVE - DELETED - PENDING - REJECTED - name: campaignIds in: query required: false description: Get ads in the given campaigns only. schema: type: array items: type: string - name: adSetIds in: query required: false description: Get ads in the given ad sets 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/AdPageResponse' '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/update/{adId}: put: operationId: updateAd tags: - Ad summary: Update an ad description: Update an ad and/or its creative. externalDocs: description: 'NewsBreak reference: Update an Ad' url: https://advertising-api.newsbreak.com/hc/en-us/articles/37869332787853-Update-an-Ad parameters: - name: adId in: path required: true description: ID of the ad to update. schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateAdRequest' 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/AdResponse' '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/updateStatus/{adId}: put: operationId: updateAdStatus tags: - Ad summary: Update ad status (ON/OFF) description: Enable or disable an ad. externalDocs: description: 'NewsBreak reference: Update Ad Status (ON/OFF)' url: https://advertising-api.newsbreak.com/hc/en-us/articles/37869330859533-Update-Ad-Status-ON-OFF parameters: - name: adId in: path required: true description: ID of the ad 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/AdResponse' '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/delete/{adId}: delete: operationId: deleteAd tags: - Ad summary: Delete an ad description: Delete an ad. externalDocs: description: 'NewsBreak reference: Delete an Ad' url: https://advertising-api.newsbreak.com/hc/en-us/articles/37869268891661-Delete-an-Ad parameters: - name: adId in: path required: true description: ID of the ad 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/AdResponse' '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/uploadAssets: post: operationId: uploadAdAssets tags: - Ad summary: Upload single ad assets description: Upload a single creative asset to the NewsBreak CDN. Only asset URLs returned by this operation are accepted by createAd / updateAd. Optionally saves the media to the ad account's Media Library. externalDocs: description: 'NewsBreak reference: Upload Single Ad Assets' url: https://advertising-api.newsbreak.com/hc/en-us/articles/37869305274509-Upload-Single-Ad-Assets requestBody: required: true content: multipart/form-data: schema: $ref: '#/components/schemas/UploadAssetRequest' 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/UploadAssetResponse' '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' /reports/getIntegratedReport: post: operationId: runSynchronousReport tags: - Report summary: Run a synchronous report description: Run a synchronous report task and return the rows inline. externalDocs: description: 'NewsBreak reference: Run a Synchronous Report' url: https://advertising-api.newsbreak.com/hc/en-us/articles/37825594764941-Run-a-Synchronous-Report requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ReportRequest' 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/ReportRowsResponse' '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' /reports/createReport: post: operationId: createCustomReport tags: - Report summary: Create a custom report description: Create a saved custom report definition that can later be run by ID. externalDocs: description: 'NewsBreak reference: Create a Custom Report' url: https://advertising-api.newsbreak.com/hc/en-us/articles/37825592263053-Create-a-Custom-Report requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ReportRequest' 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/ReportRowsResponse' '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' /reports/getReportById: get: operationId: getCustomReportById tags: - Report summary: Get a custom report by ID description: Run a previously created custom report and return its rows. externalDocs: description: 'NewsBreak reference: Get a Custom Report by Id' url: https://advertising-api.newsbreak.com/hc/en-us/articles/37825650131469-Get-a-Custom-Report-by-Id parameters: - name: reportId in: query required: true description: ID of this report. 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/ReportRowsResponse' '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' /balance/getAccountBudgetInfo: post: operationId: getAccountSpendingCap tags: - Account Billing summary: Get account spending cap description: Get account remaining budget, account lifetime spending cap and account total spend by account IDs. Users only receive accounts that have an account-level cap and that they have access to. The number of account IDs cannot be 0 or more than 500. externalDocs: description: 'NewsBreak reference: Get Account Spending Cap' url: https://advertising-api.newsbreak.com/hc/en-us/articles/40262348828173-Get-Account-Spending-Cap requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/GetAccountBudgetRequest' 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/AccountBudgetResponse' '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' /balance/updateAccountsBudget: post: operationId: updateAccountSpendingCap tags: - Account Billing summary: Update account spending cap description: Update account-level spending caps for multiple ad accounts. Only the organization admin can update the spending cap. Each account is processed individually and a per-account result is returned. externalDocs: description: 'NewsBreak reference: Update Account Spending Cap' url: https://advertising-api.newsbreak.com/hc/en-us/articles/40484091417485-Update-Account-Spending-Cap requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateAccountsBudgetRequest' 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/UpdateAccountBudgetResponse' '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' /event/getList/{adAccountId}: get: operationId: getEvents tags: - Event Management summary: Get events description: Get all conversion tracking events (pixel or postback) for an ad account. externalDocs: description: 'NewsBreak reference: Get Events' url: https://advertising-api.newsbreak.com/hc/en-us/articles/37869390553101-Get-Events parameters: - name: adAccountId in: path required: true description: ID of the ad account of the events. schema: type: string - name: os in: query required: false description: Filter events by operating system. Use os= (empty) to filter for web events. Omit to get all events. schema: type: array items: type: string enum: - IOS - ANDROID 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/EventListResponse' '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: 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. schemas: 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. Organization: type: object description: An advertising organization. properties: id: type: string description: Organization ID. name: type: string description: Organization name. 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. Campaign: type: object description: A NewsBreak advertising campaign. properties: id: type: string description: Campaign ID. name: type: string description: Campaign name. orgId: type: string description: Organization ID. adAccountId: type: string description: Ad account ID. objective: type: string description: Objective of the campaign. enum: - WEB_CONVERSION - APP_CONVERSION - REACH - WEB_TRAFFIC - APP_TRAFFIC budget: type: integer description: Campaign budget in cents. onlineStatus: type: string description: Online status of the campaign. enum: - WARNING - INACTIVE - ACTIVE - DELETED status: type: string description: Campaign status. enum: - 'ON' - 'OFF' createTime: type: string description: Create time of the campaign (unix timestamp as string). updateTime: type: string description: Update time of the campaign (unix timestamp as 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' Ad: type: object description: An ad and its creative. properties: id: type: string description: Ad ID. name: type: string description: Ad name. adAccountId: type: string description: Ad account ID. campaignId: type: string description: Campaign ID. adSetId: type: string description: Ad set ID. clickTrackingUrl: type: array description: Click tracking URL list. items: type: string impressionTrackingUrl: type: array description: Impression tracking URL list. items: type: string status: type: string description: Ad status. enum: - 'ON' - 'OFF' onlineStatus: type: string description: Online status of the ad. enum: - WARNING - INACTIVE - ACTIVE - DELETED - PENDING - REJECTED creative: $ref: '#/components/schemas/Creative' createTime: type: string description: Create time of the ad. updateTime: type: string description: Update time of the ad. Creative: type: object description: The creative rendered for an ad. properties: type: type: string description: Type of this creative. enum: - IMAGE - VIDEO - GIF - PLAYABLE_VIDEO headline: type: string description: Title. assetUrl: type: string description: URL of the IMAGE, VIDEO or GIF. Must be an asset uploaded to the NewsBreak CDN via uploadAdAssets, and include your account ID. coverUrl: type: string description: Cover image of the video. Only applicable for VIDEO and PLAYABLE_VIDEO. Must be a NewsBreak CDN asset. playableAssetUrl: type: string description: URL of the interactive playable HTML file. Required when type is PLAYABLE_VIDEO. Must be an .html asset uploaded to the NewsBreak CDN. description: type: string description: Description of this ad. callToAction: type: string description: Text on the button. brandName: type: string description: Brand name of this ad. logoUrl: type: string description: URL of the logo. clickThroughUrl: type: string description: Landing page URL. required: - type - headline - assetUrl - description - callToAction - brandName 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' 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 Event: type: object description: A conversion tracking event (pixel or postback). properties: id: type: string description: Event tracking ID, to be used on an ad set. name: type: string description: Event tracking name. orgId: type: string description: Organization ID. type: type: string description: Event type. enum: - PIXEL - POSTBACK eventType: type: string description: The event type of the tracking event. eventParams: type: array description: Attachable parameters of the tracking event. items: type: string url: type: string description: URL of the tracking event. os: type: string description: Operating system of the tracking event. enum: - IOS - ANDROID ReportRow: type: object description: One row of report data. properties: date: type: string description: Date. hour: type: string description: Hour. adAccountId: type: string description: Ad account ID. adAccount: type: string description: Ad account name. orgId: type: string description: Organization ID. organization: type: string description: Organization name. campaignId: type: string description: Campaign ID. campaign: type: string description: Campaign name. adSetId: type: string description: Ad set ID. adSet: type: string description: Ad set name. adId: type: string description: Ad ID. ad: type: string description: Ad name. placement: type: string description: Placement name. country: type: string description: Country name. costDecimal: type: number format: double description: Cost in cents. cost: type: integer description: Cost in cents. impression: type: integer description: Impressions. click: type: integer description: Clicks. conversion: type: integer description: Conversions. conversionValueDecimal: type: number format: double description: Total conversion value in cents. conversionValue: type: integer description: Total conversion value. cpmDecimal: type: number format: double description: CPM in cents, -1.0 if N/A. cpm: type: integer description: CPM in cents, -1 if N/A. cpcDecimal: type: number format: double description: CPC in cents, -1.0 if N/A. cpc: type: integer description: CPC in cents, -1 if N/A. cpaDecimal: type: number format: double description: Cost per action in cents, -1.0 if N/A. cpa: type: integer description: Cost per action in cents, -1 if N/A. ctr: type: number description: Click-through rate. ReportRequest: type: object description: A report definition, shared by runSynchronousReport and createCustomReport. properties: name: type: string description: Name of this report. timezone: type: string description: Valid timezone string, such as UTC, America/Los_Angeles or Asia/Shanghai. Default is PDT. dateRange: type: string description: Date range of the report. enum: - FIXED - YESTERDAY - LAST_7_DAYS - LAST_14_DAYS - LAST_30_DAYS - MONTH_TO_DATE - QUARTER_TO_DATE - TODAY startDate: type: string description: Start date, formatted YYYY-MM-DD. Required when dateRange is FIXED. endDate: type: string description: End date, formatted YYYY-MM-DD. Required when dateRange is FIXED. filter: type: string description: Filter type. enum: - ORG - AD_ACCOUNT - CAMPAIGN - AD_SET - AD dataSource: type: string description: Data source type. HOURLY is the official basis for income settlement on NewsBreak. enum: - HOURLY - REALTIME filterIds: type: array description: IDs matching the filter type. items: type: string dimensions: type: array description: Report dimensions (UPPERCASE only). HOUR only works with dateRange YESTERDAY, TODAY or a 1-day FIXED range; DATE works with YESTERDAY, TODAY, LAST_7_DAYS, LAST_14_DAYS, LAST_30_DAYS, MONTH_TO_DATE or a FIXED range of at most 30 days. items: type: string enum: - DATE - HOUR - ORG - AD_ACCOUNT - CAMPAIGN - AD_SET - AD - PLACEMENT metrics: type: array description: Report metrics. items: type: string emails: type: array description: Email recipients of the report. items: type: string editors: type: array description: Users allowed to edit the report. items: type: string required: - name - timezone - dateRange - dimensions - metrics 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 //, 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 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 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 CreateCampaignRequest: type: object properties: adAccountId: type: string description: ID of ad account. name: type: string description: Descriptive name of campaign. objective: type: string description: Campaign objective. enum: - WEB_CONVERSION - APP_CONVERSION - REACH - WEB_TRAFFIC - APP_TRAFFIC status: type: string description: Status of the campaign. Default is ON. enum: - 'ON' - 'OFF' required: - adAccountId - name - objective UpdateCampaignRequest: type: object properties: name: type: string description: Descriptive name of campaign. required: - name 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 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//app//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 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//app//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' CreateAdRequest: type: object properties: adSetId: type: string description: ID of ad set. name: type: string description: Descriptive name of the ad. clickTrackingUrl: type: array description: Click tracking URL list. items: type: string impressionTrackingUrl: type: array description: Impression tracking URL list. items: type: string status: type: string description: Status of the ad. Default is ON. enum: - 'ON' - 'OFF' creative: $ref: '#/components/schemas/Creative' required: - adSetId - name - creative UpdateAdRequest: type: object description: Ad fields to update. All fields are optional. properties: name: type: string description: Descriptive name of the ad. clickTrackingUrl: type: array description: Click tracking URL list. items: type: string impressionTrackingUrl: type: array description: Impression tracking URL list. items: type: string status: type: string description: Status of the ad. enum: - 'ON' - 'OFF' creative: $ref: '#/components/schemas/Creative' UploadAssetRequest: type: object properties: asset: type: string format: binary description: Asset to be uploaded. adAccountId: type: string description: ID of the ad account of the ad. saveToMediaLibrary: type: boolean description: Save the media to the account's Media Library, making it reusable in the ad platform UI. mediaName: type: string description: Media name, 3-256 characters. Required only when saveToMediaLibrary is true. required: - asset - adAccountId GetAccountBudgetRequest: type: object properties: accountIds: type: array description: IDs of ad accounts. Must be between 1 and 500 IDs. items: type: string required: - accountIds UpdateAccountsBudgetRequest: type: object properties: adAccountsBudgetUpdate: type: array description: List of account spending cap updates. items: type: object properties: adAccountId: type: string description: Ad account ID (numeric string). budget: type: integer format: int64 description: New spending cap in cents. Must be between 0 and 10,000,000,000 cents ($0-$100M), and greater than the account current total spend. If no cap is currently set, this enables and sets it. minimum: 0 maximum: 10000000000 required: - adAccountId - budget required: - adAccountsBudgetUpdate OrganizationListResponse: type: object description: Envelope carrying a list of organizations. 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: $ref: '#/components/schemas/Organization' 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' 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' CampaignResponse: type: object description: Envelope carrying a single campaign. 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/Campaign' CampaignPageResponse: type: object description: Envelope carrying a page of campaigns. 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/Campaign' 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' AdResponse: type: object description: Envelope carrying a single ad. 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/Ad' AdPageResponse: type: object description: Envelope carrying a page of ads. 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/Ad' UploadAssetResponse: type: object description: Envelope carrying an uploaded asset. 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: assetUrl: type: string description: URL of the uploaded image, video or GIF on the NewsBreak CDN. mediaId: type: string description: Media ID. ReportRowsResponse: type: object description: Envelope carrying report rows. 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: rows: type: array items: $ref: '#/components/schemas/ReportRow' AccountBudgetResponse: type: object description: Envelope carrying per-account budget information. 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: accountId: type: string description: Ad account ID. accountRemaining: type: number format: double description: Budget remaining in the account. accountSpendingCap: type: number format: double description: Account-level spending cap. accountTotalSpend: type: number format: double description: Total spent in the account. canViewBudget: type: boolean description: Whether the caller can view this account's budget. failMessage: type: string description: Reason the caller cannot view this account's budget. UpdateAccountBudgetResponse: type: object description: Envelope carrying a per-account spending cap update result. 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: adAccountId: type: string description: Ad account ID. message: type: string description: Success or failure message describing the result for this account. EventListResponse: type: object description: Envelope carrying a list of tracking events. 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: $ref: '#/components/schemas/Event'