Ad Reporting

openapi: 3.0.0 info: title: Ads Reporting description: Reporting for ads served to Consumer Users. Information on impressions and clickthroughs. version: latest servers: - url: 'https://banno.com' tags: - name: reporting description: Reports about ad performance - name: profile-exports description: Profile CSV exports paths: '/a/ads-reporting/api/v0/institutions/{institutionId}': get: description: Requires the "View digital banking ads" permission tags: - reporting security: - clientCredentials: [] parameters: - $ref: '#/components/parameters/InstitutionId' - $ref: '#/components/parameters/RequiredStart' - $ref: '#/components/parameters/RequiredEnd' - $ref: '#/components/parameters/Resolution' responses: '200': description: Returns counts aggregated to the requested institution content: application/json: schema: $ref: '#/components/schemas/InstitutionReport' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' '/a/ads-reporting/api/v0/institutions/{institutionId}/campaigns': get: deprecated: true description: Please use the `/a/ads-reporting/api/v0/institutions/{institutionId}/campaigns/{campaignId}` endpoint instead of this endpoint. It returns the same information for an individual campaign and is more performant. tags: - reporting security: - clientCredentials: [] parameters: - $ref: '#/components/parameters/InstitutionId' - $ref: '#/components/parameters/Start' - $ref: '#/components/parameters/End' responses: '200': description: >- Returns counts aggregated to each campaign for the institution. Optional time-series response fields are currently omitted in this endpoint since only the main counts are currently required. content: application/json: schema: $ref: '#/components/schemas/CampaignsReport' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' '/a/ads-reporting/api/v0/institutions/{institutionId}/campaigns/{campaignId}': get: description: Requires the "View digital banking ads" permission tags: - reporting security: - clientCredentials: [] parameters: - $ref: '#/components/parameters/InstitutionId' - $ref: '#/components/parameters/CampaignId' - $ref: '#/components/parameters/Start' - $ref: '#/components/parameters/End' - $ref: '#/components/parameters/Resolution' responses: '200': description: >- Returns counts aggregated to the requested campaign. Optional time-series response fields will be omitted unless a date range is provided. content: application/json: schema: $ref: '#/components/schemas/CampaignReport' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' '/a/ads-reporting/api/v0/institutions/{institutionId}/campaigns/{campaignId}/ads': get: description: Requires the "View digital banking ads" permission tags: - reporting security: - clientCredentials: [] parameters: - $ref: '#/components/parameters/InstitutionId' - $ref: '#/components/parameters/CampaignId' responses: '200': description: >- Returns counts aggregated to each ad for the requested campaign. Optional time-series response fields are omitted in this endpoint since it doesn't currently accept a date range. content: application/json: schema: $ref: '#/components/schemas/AdsReport' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' '/a/ads-reporting/api/v0/institutions/{institutionId}/ads/{adId}': get: description: Requires the "View digital banking ads" permission tags: - reporting security: - clientCredentials: [] parameters: - $ref: '#/components/parameters/InstitutionId' - $ref: '#/components/parameters/AdId' - $ref: '#/components/parameters/Start' - $ref: '#/components/parameters/End' - $ref: '#/components/parameters/Resolution' responses: '200': description: >- Returns counts aggregated to the requested ad. Optional time-series response fields will be omitted unless a date range is provided. content: application/json: schema: $ref: '#/components/schemas/AdReport' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' '/a/ads-reporting/api/v0/institutions/{institutionId}/campaigns/{campaignId}/users': get: description: Requires the "View digital banking ads" permission tags: - reporting security: - clientCredentials: [] parameters: - $ref: '#/components/parameters/InstitutionId' - $ref: '#/components/parameters/CampaignId' - $ref: '#/components/parameters/Start' - $ref: '#/components/parameters/End' responses: '200': description: >- Returns the count of users who have received impressions and clickthroughs for the campaign. content: application/json: schema: $ref: '#/components/schemas/CampaignUserCountResponse' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' '/a/ads-reporting/api/v0/institutions/{institutionId}/campaigns/{campaignId}/segments/{segmentId}/users': get: description: Requires the "View digital banking ads" permission tags: - reporting security: - clientCredentials: [] parameters: - $ref: '#/components/parameters/InstitutionId' - $ref: '#/components/parameters/CampaignId' - $ref: '#/components/parameters/SegmentId' responses: '200': description: >- Returns a summary of the segment users that have interacted with the campaign. The list of users will be restricted to only segments with 150 or less users. Large segments will return an empty users list. content: application/json: schema: $ref: '#/components/schemas/SegmentUsersReport' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' '/a/ads-reporting/api/v0/institutions/{institutionId}/campaigns/{campaignId}/profile-exports': post: description: Requires the "Edit digital banking ads" permission tags: - profile-exports security: - clientCredentials: [] parameters: - $ref: '#/components/parameters/InstitutionId' - $ref: '#/components/parameters/CampaignId' requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateProfileExport' responses: '200': description: >- Asynchronously requests a profiles CSV to be created. Returns metadata for the export file. content: application/json: schema: $ref: '#/components/schemas/ProfileExport' '500': $ref: '#/components/responses/500' get: description: Requires the "View digital banking ads" permission tags: - profile-exports security: - clientCredentials: [] parameters: - $ref: '#/components/parameters/InstitutionId' - $ref: '#/components/parameters/CampaignId' responses: '200': description: Returns metadata for a list of export files content: application/json: schema: $ref: '#/components/schemas/ProfileExports' '500': $ref: '#/components/responses/500' '/a/ads-reporting/api/v0/institutions/{institutionId}/campaigns/{campaignId}/profile-exports/{profileExportId}': get: description: Requires the "View digital banking ads" permission tags: - profile-exports security: - clientCredentials: [] parameters: - $ref: '#/components/parameters/InstitutionId' - $ref: '#/components/parameters/CampaignId' - $ref: '#/components/parameters/ProfileExportId' responses: '200': description: Returns metadata for the export file. content: application/json: schema: $ref: '#/components/schemas/ProfileExport' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' delete: description: Requires the "Edit digital banking ads" permission tags: - profile-exports security: - clientCredentials: [] parameters: - $ref: '#/components/parameters/InstitutionId' - $ref: '#/components/parameters/CampaignId' - $ref: '#/components/parameters/ProfileExportId' responses: '204': $ref: '#/components/responses/204' '500': $ref: '#/components/responses/500' '/a/ads-reporting/api/v0/institutions/{institutionId}/campaigns/{campaignId}/profile-exports/{profileExportId}.csv': get: description: Requires the "View digital banking ads" permission tags: - profile-exports security: - clientCredentials: [] parameters: - $ref: '#/components/parameters/InstitutionId' - $ref: '#/components/parameters/CampaignId' - $ref: '#/components/parameters/ProfileExportId' responses: '200': description: >- Returns content-disposition of the csv file. The file will only be available if the report is created (having createdAt set to the create datetime) and if the report has results (having totalUsersCount > 0). A 404 will be returned until then. '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' components: securitySchemes: clientCredentials: type: oauth2 description: OAuth2 using the client credentials flow flows: clientCredentials: tokenUrl: https://banno.com/a/oidc-provider/api/v0/token scopes: {} responses: '204': description: 'The request finished, returning no content.' '404': description: The specified resource was not found '500': description: There was an internal server error parameters: InstitutionId: in: path name: institutionId required: true schema: type: string description: institution id for request CampaignId: in: path name: campaignId required: true schema: type: string description: campaign id for request AdId: in: path name: adId required: true schema: type: string description: ad id for request SegmentId: in: path name: segmentId required: true schema: type: string description: segment id for request ProfileExportId: in: path name: profileExportId required: true schema: type: string description: profile export id for request Start: in: query name: start required: false schema: type: string description: 'time-series request start date, format yyyy-MM-dd' End: in: query name: end required: false schema: type: string description: 'time-series request end date, format yyyy-MM-dd' RequiredStart: in: query name: start required: true schema: type: string description: 'time-series request start date, format yyyy-MM-dd' RequiredEnd: in: query name: end required: true schema: type: string description: 'time-series request end date, format yyyy-MM-dd' Resolution: in: query name: resolution required: false schema: type: string description: >- time-series interval size, accepting values of hour, day, week, month. defaults to day. schemas: TimeSeriesInterval: type: object properties: impressionCount: type: number clickthroughCount: type: number clickthroughRate: type: number startDate: type: string format: ISO8601 endDate: type: string format: ISO8601 InstitutionReport: type: object required: - institutionId - totalImpressionCount - totalImpressionCountPrevious - totalClickthroughCount - totalClickthroughCountPrevious - clickthroughRate - clickthroughRatePrevious - summaryTimeSeries properties: institutionId: type: string format: UUID totalImpressionCount: type: number totalImpressionCountPrevious: type: number totalClickthroughCount: type: number totalClickthroughCountPrevious: type: number clickthroughRate: type: number clickthroughRatePrevious: type: number summaryTimeSeries: type: array items: $ref: '#/components/schemas/TimeSeriesInterval' CampaignReport: type: object required: - campaignId - totalImpressionCount - totalClickthroughCount - clickthroughRate properties: campaignId: type: string format: UUID totalImpressionCount: type: number totalImpressionCountPrevious: type: number totalClickthroughCount: type: number totalClickthroughCountPrevious: type: number clickthroughRate: type: number clickthroughRatePrevious: type: number summaryTimeSeries: type: array items: $ref: '#/components/schemas/TimeSeriesInterval' AdReport: type: object required: - adId - totalImpressionCount - totalClickthroughCount - clickthroughRate properties: adId: type: string format: UUID totalImpressionCount: type: number totalImpressionCountPrevious: type: number totalClickthroughCount: type: number totalClickthroughCountPrevious: type: number clickthroughRate: type: number clickthroughRatePrevious: type: number summaryTimeSeries: type: array items: $ref: '#/components/schemas/TimeSeriesInterval' CampaignsReport: type: object required: - campaigns properties: campaigns: $ref: '#/components/schemas/CampaignReport' AdsReport: type: object required: - ads properties: ads: $ref: '#/components/schemas/AdReport' CampaignUserCountResponse: type: object required: - campaignId - userCount - userImpressionCount - userClickthroughCount properties: campaignId: type: string format: UUID userCount: type: number userImpressionCount: type: number userClickthroughCount: type: number SegmentUserReport: type: object required: - userId - impression - clickthrough properties: userId: type: string format: UUID impression: type: boolean clickthrough: type: boolean SegmentUsersReport: type: object required: - campaignId - segmentId - users properties: campaignId: type: string format: UUID segmentId: type: string format: UUID userCount: type: number userImpressionCount: type: number userClickthroughCount: type: number users: type: array items: $ref: '#/components/schemas/SegmentUserReport' CreateProfileExport: type: object required: - exportName properties: exportName: type: string description: >- The filename of the completed CSV file when being downloaded, not including the csv extension. exportStart: type: string description: Optional yyyy-MM-dd date to filter the report by start time. exportEnd: type: string description: Optional yyyy-MM-dd date to filter the report by end time. ProfileExport: type: object required: - profileExportId - institutionId - campaignId - exportName - submittedAt - createdBy properties: profileExportId: type: string format: uuid institutionId: type: string format: uuid campaignId: type: string format: uuid exportName: type: string description: >- The filename of the completed CSV file when being downloaded, not including the csv extension. exportStart: type: string description: Optional yyyy-MM-dd date to filter the report by start time. exportEnd: type: string description: Optional yyyy-MM-dd date to filter the report by end time. submittedAt: type: string description: Datetime when the report is requested. createdBy: $ref: '#/components/schemas/ProfileExportCreatedBy' createdAt: type: string description: >- DateTime when the report CSV is created and ready for download via the csv endpoint. This value will be NULL until the report is created! totalUsersCount: type: number description: >- Total users in the completed CSV file. This value will be 0 until the report is created! totalImpressionUsersCount: type: number description: >- Total users in the completed CSV file having impressions. This value will be 0 until the report is created! totalClickthroughUsersCount: type: number description: >- Total users in the completed CSV file having clickthroughs. This value will be 0 until the report is created! ProfileExportCreatedBy: type: object required: - userId properties: userId: type: string userName: type: string ProfileExports: type: object required: - exports properties: exports: type: array items: $ref: '#/components/schemas/ProfileExport'