Sourcepoint U.S. Multi-State Privacy reporting API

openapi: 3.2.0
info:
  title: Sourcepoint Reporting U.S. Multi-State Privacy U.S. Multi-State Privacy reporting API
  version: 1.0.0
  description: Sourcepoint Technologies API for retrieving U.S. Multi-State Privacy dashboard report data.
servers:
- url: https://portal.sourcepoint.com/api/external/v1/reports
security:
- ApiKeyAuth: []
tags:
- name: U.S. Multi-State Privacy reporting API
paths:
  /usnat/dashboard-v2-pv-users/{periodFilter}:
    post:
      tags:
      - U.S. Multi-State Privacy reporting API
      description: Returns pageview data for properties that have implemented U.S. Multi-State Privacyy.<br><br>Include your API key in the provided **Header** field under **AUTHORIZATION** in the right-hand pane before trying your request.<br><br>In addition to the API key, you will also need to include 'startDate', 'endDate', and `siteId` in your request.
      summary: U.S. Multi-State Privacy pageview data
      parameters:
      - $ref: '#/components/parameters/periodFilter'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/usmspPvRequestBody'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/usmspPvResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
  /usnat/dashboard-v2-messages/{periodFilter}:
    post:
      tags:
      - U.S. Multi-State Privacy reporting API
      description: Returns message data for properties that have implemented U.S. Multi-State Privacy.<br><br>Include your API key in the provided **Header** field under **AUTHORIZATION** in the right-hand pane before trying your request.<br><br>In addition to the API key, you will also need to include `startDate`, `endDate`, and `siteId` in your request.
      summary: U.S. Multi-State Privacy message data
      parameters:
      - $ref: '#/components/parameters/periodFilter'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/usmspMsgRequestBody'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/usmspMsgResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
components:
  responses:
    UnauthorizedError:
      description: API key is missing or invalid
      headers:
        WWW-Authenticate:
          schema:
            type: string
  schemas:
    usmspMsgResponse:
      type: object
      description: Successful response for U.S. Multi-State Privacy message report request
      properties:
        performanceData:
          type: object
          description: Ignore. For internal troubleshooting.
          properties:
            total:
              type: integer
            messagesResults:
              type: integer
        results:
          type: array
          items:
            type: object
            properties:
              ymd:
                type: string
                description: Year, month and day. Returned only for Daily periodization
                example: '2023-09-02T00:00:00.000Z'
              geo:
                type: string
                description: Geographic region to which the results pertain. Returned when request uses geo in the breakdownBy parameter
                example: US
              state:
                type: string
                description: US state to which the results pertain. Returned when request uses state in the breakdownBy parameter
                example: CA
              ua_os:
                type: string
                description: Operating system type to which the results pertain. Returned when request uses ua_os in the breakdownBy parameter
                example: macOS
              ua_device:
                type: string
                description: Device type to which the results pertain. Returned when request uses ua_device in the breakdownBy parameter
                example: desktop
              ua_browser:
                type: string
                description: Browser type to which the results pertain. Returned when request uses ua_browser in the breakdownBy parameter
                example: Chrome
              site_id:
                type: string
                description: Property ID within the Sourcepoint portal
                example: 12345
              property_name:
                type: string
                description: Domain reported upon
                example: '"www.sourcepoint.com"'
              'Message Actions: Total':
                type: number
                description: Total number of end-user actions
                example: 2
              'Message Actions: Sell Opted-in':
                type: number
                description: Total number of actions on messages whose latest choice included an opt into the sale of personal information privacy choice
                example: 2
              'Message Actions: Sell Opted-out':
                type: number
                description: Total number of actions on messages whose latest choice included an opt out of the sale of personal information privacy choice
                example: 0
              'Message Actions: Share Opted-in':
                type: number
                description: Total number of actions on messages whose latest choice included an opt into the sharing of personal information privacy choice
                example: 2
              'Message Actions: Share Opted-out':
                type: number
                description: Total number of actions on messages whose latest choice included an opt out of the sharing of personal information privacy choice
                example: 0
              'Message Actions: Sensitive Data Opted-in':
                type: number
                description: Total number of actions on messages whose latest choice included an opt into sensitive data privacy choices
                example: 2
              'Message Actions: Sensitive Data Opted-out':
                type: number
                description: Total number of actions on messages whose latest choice included an opt out of sensitive data privacy choices
                example: 0
              'Message Actions: GPC Enabled':
                type: number
                description: Total number of actions on messages whose latest choice was made using a browser with the Global Privacy Control setting enabled
                example: 0
              'Message Actions: GPC Disabled':
                type: number
                description: Total number of actions on messages whose latest choice was made using a browser with the Global Privacy Control setting disabled
                example: 2
    usmspMsgRequestBody:
      description: Request body for US Multi-State Privacy message reporting data request
      type: object
      properties:
        startDate:
          type: string
          description: Start date for the periodization. Format YYYY-MM-DD
          example: YYYY-MM-DD
        endDate:
          type: string
          description: End date for the periodization. Format YYYY-MM-DD
          example: YYYY-MM-DD
        siteId:
          type: array
          description: Array of property IDs in the Sourcepoint portal that will be included in the report data.
          items:
            type: string
          example:
          - 22
          - 1584
        geo:
          type: array
          description: Array of alpha-2 country codes (ISO 3166-1) that will be included in the report data. Preset regions (EU, EEA, etc...) is *not* permitted. If geo property is omitted then *all* countries and regions will be included in the report data.
          items:
            type: string
          example:
          - US
        state:
          type: array
          description: Array of alpha-2 state codes (ISO 3166-2:US) that will be included in the report data. If state property is omitted then *all* US states will be included in the report data.
          items:
            type: string
          example:
          - CA
        device:
          type: array
          items:
            type: string
            enum:
            - desktop
            - mobile
            - tablet
            - tv
          description: Array of devices that will be included in the report data. If device property is omitted then *all* devices will be included in report data.
          example:
          - desktop
          - mobile
        browser:
          type: array
          description: Array of browsers that will be included in the report data. If browser property is omitted then *all* browsers will be included in report data.
          items:
            type: string
            enum:
            - Amazon Silk
            - Android Browser
            - Bada
            - BlackBerry
            - Chrome
            - Chromium
            - Epiphany
            - Firefox
            - Focus
            - Generic
            - Googlebot
            - Internet Explorer
            - K-Meleon
            - Maxthon
            - Microsoft Edge
            - MZ Browser
            - NAVER Whale Browser
            - Opera
            - Opera Coast
            - PhantomJS
            - Puffin
            - QupZilla
            - Safari
            - Sailfish
            - Samsung Internet for Android
            - SeaMonkey
            - Sleipnir
            - Swing
            - Tizen
            - UC Browser
            - WebOS Browser
            - WeChat
            - Yandex Browser
          example:
          - Firefox
          - Chrome
        os:
          type: array
          description: Array of operating systems that will be included in the report data. If os property is omitted then *all* operating systems will be included in report data.
          items:
            type: string
            enum:
            - Windows
            - iOS
            - Windows Phone
            - MacOS
            - Android
            - WebOS
            - BlackBerry
            - Bada
            - Tizen
            - Linux
            - Chrome OS
            - Playstation 4
            - Roku
          example:
          - Windows
          - MacOS
        breakdownBy:
          type: array
          description: Array of different parameters that can be selected to breakdown/organize the returned results. Options include geo, state, message ID (msg_id), operating system (ua_os), device (ua_device), browser (ua_browser)
          items:
            type: string
            enum:
            - geo
            - state
            - msg_id
            - ua_os
            - ua_device
            - ua_browser
          example:
          - state
      required:
      - startDate
      - endDate
      - siteId
    usmspPvRequestBody:
      description: Request body for US Multi-State Privacy page view reporting data request
      type: object
      properties:
        startDate:
          type: string
          description: Start date for the periodization. Format YYYY-MM-DD
          example: YYYY-MM-DD
        endDate:
          type: string
          description: End date for the periodization. Format YYYY-MM-DD
          example: YYYY-MM-DD
        siteId:
          type: array
          description: Array of property IDs in the Sourcepoint portal that will be included in the report data.
          items:
            type: string
          example:
          - 22
          - 1584
        geo:
          type: array
          description: Array of alpha-2 country codes (ISO 3166-1) that will be included in the report data. Preset regions (EU, EEA, etc...) is *not* permitted. If geo property is omitted then *all* countries and regions will be included in the report data.
          items:
            type: string
          example:
          - US
        state:
          type: array
          description: Array of alpha-2 state codes (ISO 3166-2:US) that will be included in the report data. If state property is omitted then *all* US states will be included in the report data.
          items:
            type: string
          example:
          - CA
        device:
          type: array
          items:
            type: string
            enum:
            - desktop
            - mobile
            - tablet
            - tv
          description: Array of devices that will be included in the report data. If device property is omitted then *all* devices will be included in report data.
          example:
          - desktop
          - mobile
        browser:
          type: array
          description: Array of browsers that will be included in the report data. If browser property is omitted then *all* browsers will be included in report data.
          items:
            type: string
            enum:
            - Amazon Silk
            - Android Browser
            - Bada
            - BlackBerry
            - Chrome
            - Chromium
            - Epiphany
            - Firefox
            - Focus
            - Generic
            - Googlebot
            - Internet Explorer
            - K-Meleon
            - Maxthon
            - Microsoft Edge
            - MZ Browser
            - NAVER Whale Browser
            - Opera
            - Opera Coast
            - PhantomJS
            - Puffin
            - QupZilla
            - Safari
            - Sailfish
            - Samsung Internet for Android
            - SeaMonkey
            - Sleipnir
            - Swing
            - Tizen
            - UC Browser
            - WebOS Browser
            - WeChat
            - Yandex Browser
          example:
          - Firefox
          - Chrome
        os:
          type: array
          description: Array of operating systems that will be included in the report data. If os property is omitted then *all* operating systems will be included in report data.
          items:
            type: string
            enum:
            - Windows
            - iOS
            - Windows Phone
            - MacOS
            - Android
            - WebOS
            - BlackBerry
            - Bada
            - Tizen
            - Linux
            - Chrome OS
            - Playstation 4
            - Roku
          example:
          - Windows
          - MacOS
        breakdownBy:
          type: array
          description: Array of different parameters that can be selected to breakdown/organize the returned results. Options include geo, state, operating system (ua_os), device (ua_device), browser (ua_browser)
          items:
            type: string
            enum:
            - geo
            - state
            - ua_os
            - ua_device
            - ua_browser
          example:
          - state
      required:
      - startDate
      - endDate
      - siteId
    usmspPvResponse:
      type: object
      description: Successful response for U.S. Multi-State Privacy pageview report request
      properties:
        performanceData:
          type: object
          description: Ignore. For internal troubleshooting.
          properties:
            total:
              type: integer
            messagesResults:
              type: integer
        results:
          type: array
          items:
            type: object
            properties:
              ymd:
                type: string
                description: Year, month and day. Returned only for Daily periodization
                example: '2023-09-02T00:00:00.000Z'
              geo:
                type: string
                description: Geographic region to which the results pertain. Returned when request uses geo in the breakdownBy parameter
                example: US
              state:
                type: string
                description: US state to which the results pertain. Returned when request uses state in the breakdownBy parameter
                example: CA
              ua_os:
                type: string
                description: Operating system type to which the results pertain. Returned when request uses ua_os in the breakdownBy parameter
                example: macOS
              ua_device:
                type: string
                description: Device type to which the results pertain. Returned when request uses ua_device in the breakdownBy parameter
                example: desktop
              ua_browser:
                type: string
                description: Browser type to which the results pertain. Returned when request uses ua_browser in the breakdownBy parameter
                example: Chrome
              site_id:
                type: string
                description: Property ID within the Sourcepoint portal
                example: 12345
              property_name:
                type: string
                description: Domain reported upon
                example: '"www.sourcepoint.com"'
              'Page Views: Total':
                type: number
                description: Total number of page views for the given periodization
                example: 2
              'Page Views: Sell Opted-in':
                type: number
                description: Page views across users who have opted into the sale of personal information privacy choice
                example: 2
              'Page Views: Sell Opted-out':
                type: number
                description: Page views across users who have opted out of the sale of personal information privacy choice
                example: 0
              'Page Views: Share Opted-in':
                type: number
                description: Page views across users who have opted into the sharing of personal information privacy choice
                example: 2
              'Page Views: Share Opted-out':
                type: number
                description: Page views across users who have opted out of the sharing of personal information privacy choice
                example: 0
              'Page Views: Sensitive Data Opted-in':
                type: number
                description: Page views across users who have opted into sensitive data privacy choices
                example: 0
              'Page Views: Sensitive Data Opted-out':
                type: number
                description: Page views across users who have opted out of sensitive data privacy choices
                example: 2
              'Page Views: GPC Enabled':
                type: number
                description: Page views across users who had the Global Privacy Control setting enabled on their browser
                example: 0
              'Page Views: GPC Disabled':
                type: number
                description: Page views across users who had the Global Privacy Control setting disabled on their browser
                example: 2
              'Users: Total':
                type: number
                description: Total number of users for the selected properties in the configured periodization
                example: 1
              'Users: Sell Opted-in':
                type: number
                description: Unique users who have opted into the the sale of personal information privacy choice
                example: 1
              'Users: Sell Opted-out':
                type: number
                description: Unique users who have opted out of the sale of personal information privacy choice
                example: 0
              'Users: Share Opted-in':
                type: number
                description: Unique users who have opted into the sharing of personal information privacy choice
                example: 1
              'Users: Share Opted-out':
                type: number
                description: Unique users who have opted out of the sharing of personal information privacy choice
                example: 0
              'Users: Sensitive Data Opted-in':
                type: number
                description: Unique users who have opted into sensitive data privacy choices
                example: 0
              'Users: Sensitive Data Opted-out':
                type: number
                description: Unique users who have opted out of sensitive data privacy choices
                example: 1
              'Users: GPC Enabled':
                type: number
                description: Unique users who had the Global Privacy Control setting enabled on their browser
                example: 0
              'Users: GPC Disabled':
                type: number
                description: Unique users who had the Global Privacy Control setting disabled on their browser
                example: 1
  parameters:
    periodFilter:
      name: periodFilter
      in: path
      description: '- **Daily**: The maximum duration of this period is 31 days between the `startDate` and `endDate`

        - **Weekly**: A week is a period of 7 days that starts on a Monday and ends on a Sunday. If the requested `startDate` is not a Monday, Sourcepoint will backdate the reporting period to the Monday for the week in its reporting aggregation.

        - **Monthly**: A month begins on the first day of that month. If the requested `startDate` is not the first day of the month, Sourcepoint will backdate the reporting period to the first day of the month in its reporting aggregation.

        '
      required: true
      schema:
        type: string
        enum:
        - daily
        - weekly
        - monthly
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
x-readme:
  explorer-enabled: true
  proxy-enabled: true