openapi: 3.1.0
info:
  title: Brand Clicks API
  version: v11
  description: "Manage referral events (clicks/taps) representing traffic sent by\
    \ partners. \nThis API allows for retrieving specific click details and scheduling\
    \ asynchronous bulk exports \nof click data for reporting and analytics.\n"
servers:
- url: https://api.impact.com
paths:
  /Advertisers/{AccountSID}/Campaigns/{CampaignId}/Clicks/{ClickId}:
    get:
      operationId: getClickById
      tags:
      - Clicks
      summary: Retrieve a click
      description: "Retrieves the details of a click using the generated ClickId (irclickid).\
        \ \nNote: A single Id can be associated with multiple clicks in a consumer\
        \ journey. \nRate limits apply to this endpoint.\n"
      parameters:
      - name: AccountSID
        in: path
        required: true
        description: The unique identifier for the account.
        schema:
          type: string
      - name: CampaignId
        in: path
        required: true
        description: The ID of the program (campaign) associated with the click.
        schema:
          type: integer
      - name: ClickId
        in: path
        required: true
        description: The generated ClickId (or irclickid) representing the consumer journey.
        schema:
          type: string
      responses:
        '200':
          description: Returns a click object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Click'
  /Advertisers/{AccountSID}/Programs/{ProgramId}/ClickExport:
    get:
      operationId: exportClicks
      tags:
      - Clicks
      summary: Export clicks
      description: "Schedules an asynchronous job to export click data. Returns a\
        \ URI to poll for job status \nand a URI to download the result. If a call\
        \ is made with identical parameters to an existing \njob, information for\
        \ the existing job is returned.\n"
      parameters:
      - name: AccountSID
        in: path
        required: true
        description: The unique identifier for the account.
        schema:
          type: string
      - name: ProgramId
        in: path
        required: true
        description: The ID of the program (campaign) to export clicks from.
        schema:
          type: integer
      - name: AdId
        in: query
        required: false
        explode: true
        description: Id of the ad that was clicked. Can be repeated for multiple ads.
        schema:
          type: array
          items:
            type: integer
      - name: Date
        in: query
        required: false
        description: Click date in yyyy-MM-dd format. Defaults to today's date.
        schema:
          type: string
          format: date
      - name: MediaId
        in: query
        required: false
        explode: true
        description: Unique identifier of the partner. Can be repeated for multiple
          partners.
        schema:
          type: array
          items:
            type: integer
      - name: UniqueClick
        in: query
        required: false
        description: Filter by IAB standard unique clicks.
        schema:
          type: boolean
      - name: ResultFormat
        in: query
        required: false
        description: Desired return format. Defaults to CSV.
        schema:
          type: string
          enum:
          - CSV
          - XML
          - JSON
      responses:
        '200':
          description: Job successfully queued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
components:
  schemas:
    Click:
      type: object
      properties:
        Id:
          type: string
          example: abcdefg1hijkl2mn3opq4rStUvwxyz5a6bcdef7
          description: A generated value that represents the consumer journey — also
            known as im_ref . This value can be associated with multiple click objects.
        CampaignId:
          type: integer
          example: '1000'
          description: Program (formerly known as campaign ) Id associated with the
            click.
        CampaignName:
          type: string
          example: Acme Campaign
          description: Program (formerly known as campaign ) name associated with
            the click.
        ProfileId:
          type: string
          example: ab12345c-6789-0123-4de5-678f90g123h4
          description: impact.com's unique identifier for a user on a specific device.
        IpAddress:
          type: string
          example: abcdefghijklmnopqrstuvwxyz1234567890
          description: Hashed IP address that the click was sourced from. This attribute
            is used to determine Customer attributes (e.g., CustomerCity ).
        EventDate:
          type: string
          format: date-time
          example: '2021-01-25T08:06:24-05:00'
          description: Date and time this click happened. See ISO 8601 .
        MediaId:
          type: integer
          example: '10000'
          description: Partner Id that drove the click.
        MediaName:
          type: string
          example: Partner Person
          description: Partner name that drove the click.
        AdId:
          type: integer
          example: '656565'
          description: Id of the ad that was clicked.
        AdName:
          type: string
          example: Our Anvils Are Awesome
          description: Name of the ad that was clicked.
        AdType:
          type: string
          enum:
          - BANNER
          - EMAIL
          - FLASH
          - TEXT
          - TEXT_LINK
          - LONG_SPONSORED_TEXT
          - XML_SYNDICATION
          - COUPON
          - CONTENT
          - VIDEO
          - ONLINE_TRACKING_LINK
          - MEDIA_SOURCE_TRACKING
          example: BANNER
          description: Type of the ad that was clicked.
        ProductSku:
          type: string
          description: SKU of the item the ad is marketing.
          example: '12345'
        BrandRelated:
          type: object
          properties:
            AdCampaign:
              type: string
              example: Summer Sale
            AdGroup:
              type: string
              example: Tennis Equipment
            Keyword:
              type: string
              example: tennis balls
            MatchType:
              type: string
              example: BROAD
            Channel:
              type: string
              example: GOOGLE_SHOPPING
          description: Your brand's information that is related to the click event.
        CustomerArea:
          type: string
          example: n/a
          description: Generated from the IpAddress attribute, this is the geographical
            area from where the customer generated the click. If IpAddress was not
            tracked, n/a will appear.
        CustomerCity:
          type: string
          example: n/a
          description: Generated from the IpAddress attribute, this is the city from
            where the customer generated the click. If IpAddress was not tracked,
            n/a will appear.
        CustomerRegion:
          type: string
          example: n/a
          description: Generated from the IpAddress attribute, this is the geographical
            region from where the customer generated the click. If IpAddress was not
            tracked, n/a will appear.
        CustomerCountry:
          type: string
          example: US
          description: Generated from the IpAddress attribute, this is the country
            from where the customer generated the click. If IpAddress was not tracked,
            n/a will appear. See ISO 3166-1 alpha-2 .
        DeviceType:
          type: string
          enum:
          - DESKTOP
          - PHONE
          - TABLET
          - GAME
          - WATCH
          - TV
          - ROBOT
          - CAR
          - UNKNOWN
          example: UNKNOWN
          description: What device the customer clicked or tapped the ad on.
        DeviceFamily:
          type: string
          example: 'null'
          description: General group of devices that the attribute DeviceType comes
            from. Only a sample of all enum values are presented below.
        Browser:
          type: string
          example: 'null'
          description: Which web browser the customer used when they generated the
            click. Only a sample of all enum values are presented below.
        Os:
          type: string
          example: 'null'
          description: Which operating system the customer used when they generated
            the click. Only a sample of all enum values are presented below.
        ReferringUrl:
          type: string
          format: uri
          description: The URL that the customer came from when they generated the
            click.
          example: https://www.google.com/
        ReferringDomain:
          type: string
          example: NA
          description: The web domain that the customer came from when they generated
            the click.
        LandingPageUrl:
          type: string
          format: uri
          example: http://google.com?irgwc=1
          description: The URL the customer landed on when they generated the click.
        SharedId:
          type: string
          description: A SharedId that is passed on the tracking link the partner
            used.
        UniqueClick:
          type: boolean
          example: 'true'
          description: If the click follows IAB standards for a "unique click."
        CpcBid:
          type: string
          example: '0.0'
          description: How much the partner will be paid for driving the click.
        DealName:
          type: string
          description: Name of the associated deal.
        DealType:
          type: string
          enum:
          - BOGO
          - FREE_SHIPPING
          - GENERAL_SALE
          - GIFT_WITH_PURCHASE
          - REBATE
          description: Type of the associated deal.
        DealScope:
          type: string
          enum:
          - CATEGORY
          - ENTIRE_STORE
          - PRODUCT
          description: To what extent the deal applies to the click.
        PartnerRelated:
          type: object
          properties:
            SubId1:
              type: string
              example: subid1value
            SubId2:
              type: string
              example: subid2value
            SubId3:
              type: string
              example: subid3value
          description: A partner's information that is related to the click event.
        Payout:
          type: number
          format: decimal
          description: Partner's payout for driving the click.
          example: 5.00
        TrafficCategory:
          type: string
          description: What kind of traffic is generating the click.
          example: AFFILIATE
        TrafficSource:
          type: string
          description: Referring site (aka Source ) of the traffic generating the
            click.
          example: CONTENT
        BidKeyword:
          type: string
          description: If the click was generated from a Paid Search, then this will
            be the keyword used in that Paid search.
          example: tennis balls
        SearchText:
          type: string
          description: If the click was generated from a Paid Search, then this will
            be the search query the customer put into a search engine.
          example: best tennis balls
    JobResponse:
      type: object
      properties:
        Status:
          type: string
          example: QUEUED
        QueuedUri:
          type: string
          format: uri-reference
          description: URI to poll for status updates via the Jobs endpoint.
          example: /Advertisers/<AccountSID>/Jobs/3e402014-cf9e-4b3b-a010-db84cb70727a
        ResultUri:
          type: string
          format: uri-reference
          description: URI to download the job result file once completed.
          example: /Advertisers/<AccountSID>/Jobs/3e402014-cf9e-4b3b-a010-db84cb70727a/Download
        ReplayUri:
          type: string
          format: uri-reference
          description: URI to replay the export job.
          example: /Advertisers/<AccountSID>/Jobs/3e402014-cf9e-4b3b-a010-db84cb70727a/Replay
