openapi: 3.1.0
info:
  title: Brand API - Page Load Tracking
  description: |-
    API for tracking a page load or mobile app open, which is used to attribute credit for a conversion that results from a partner driving traffic.
    This endpoint is unauthenticated and intended for high-volume client-side (web/mobile) requests.
  version: v12
servers:
- url: https://trkapi.impact.com
  description: Tracking API Server
paths:
  /PageLoad:
    post:
      summary: Track a Page Load or App Open
      description: |-
        Tracks a user session start, either from a web page load or a mobile app open.
        This endpoint returns a `clickId` which should be captured and can be used later to attribute a conversion.
      operationId: trackPageLoad
      tags:
      - Tracking
      requestBody:
        description: Details about the page load or app open event.
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - CampaignId
              - EventDate
              - PageUrl
              - CustomProfileId
              properties:
                CampaignId:
                  type: integer
                  description: Unique identifier for your program (campaign).
                  example: 1000
                PageUrl:
                  type: string
                  format: uri
                  description: "**Required.** Destination URL that is intercepted by the app.\n\n- If the app open occurs from an impact.com tracking link, send the full tracking link (e.g., `https://mysite.pxf.io/c/1234567/12345/1234?sharedid=abcd`).\n- If the app is opened directly (e.g., not redirected from a URL), do not send any value.\n- If the app open occurs from a non-Impact URL, send the actual URL with `https:` (e.g., `https://www.example.com?name=value`).\n- If the app open occurs using a custom URI scheme, send the full URI (e.g., `app://view?sharedid=abcd`).\n\n**Tip:** When testing clicks and events, append `?impacttest=1` to your `PageUrl`."
                  example: https://www.acme.com/products/tennis-balls
                PropertyId:
                  type: integer
                  description: '**Required for mobile/app opens.** For mobile app opens, this value is the "System App ID" of your app in impact.com. Found in Settings → Mobile Apps.'
                  example: 12345
                AppleIfa:
                  type: string
                  description: '**Required for iOS app opens.** Apple ID for Advertising (IDFA) associated with the mobile device the customer converted on. Used for attribution purposes. Typically only available for iOS in-app conversions.'
                  example: 38400000-8cf0-11bd-b23e-10b96e40000d
                GoogAId:
                  type: string
                  description: '**Required for Android app opens.** Google Advertising ID associated with the mobile device the customer converted on. Used for attribution purposes. Typically only available for Android in-app conversions.'
                  example: 38400000-8cf0-11bd-b23e-10b96e40000d
                EventDate:
                  type: string
                  format: date-time
                  description: The timestamp of the event in ISO 8601 format.
                  example: '2026-09-10T22:55:32-08:00'
                ReferringUrl:
                  type: string
                  format: uri
                  description: The URL of the website that originated the click.
                  example: https://www.google.com/
                CustomProfileId:
                  type: string
                  description: 'Your unique identifier for an anonymous website visitor. If CustomProfileId is not provided, please provide at least one of the following identifiers: GoogAId, AndroidId, AppleIfa, AppleIfv, ClickId, or CustomerId.'
                  example: a1b2c3d4e5f6
                CustomerId:
                  type: string
                  description: Your non-PII unique identifier for the customer.
                  example: BCZ2WVSH674563PDPYOTM3AXDQ
                CustomerEmail:
                  type: string
                  description: Customer's email address (plain text or SHA1 hashed).
                  example: customer@gmail.com
                TrackingConsent:
                  type: boolean
                  description: Indicates if the user has provided consent to be tracked.
                  example: true
                UserAgent:
                  type: string
                  description: The user agent string of the browser or device.
                  example: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36
                AppleIfv:
                  type: string
                  description: Apple ID for Vendors (IDFV), for iOS apps.
                  example: 38400000-8cf0-11bd-b23e-10b96e40000d
                IpAddress:
                  type: string
                  description: Public IP address of the user.
                  example: 72.194.216.61
                AppName:
                  type: string
                  description: Name of the mobile app.
                  example: Acme App
                AppPackage:
                  type: string
                  description: Package name/bundle ID of the mobile app.
                  example: com.acme.app
                AppVer:
                  type: string
                  description: Version of the mobile app.
                  example: 1.2.3
                DeviceMfr:
                  type: string
                  description: Manufacturer of the mobile device (e.g., "Apple").
                  example: Apple
                DeviceModel:
                  type: string
                  description: Model of the mobile device (e.g., "iPhone13,2").
                  example: iPhone 15
      responses:
        '200':
          description: Successfully tracked the event. The response will contain a clickId and either a landingPage or sessionStart. It may also include warnings.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/PageLoadResponseGateway'
                - $ref: '#/components/schemas/PageLoadResponseDirect'
        '400':
          description: Bad Request. The request was invalid due to missing or malformed parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -L \
            --request POST \
            --url 'https://api.impact.com/PageLoad' \
            --user '{AccountSID}:{AuthToken}' \
            --header 'Content-Type: application/x-www-form-urlencoded' \
            --header 'Accept: */*'
components:
  schemas:
    PageLoadResponseGateway:
      type: object
      properties:
        landingPage:
          type: string
          format: uri
          description: The destination landing page URL. Present when PageUrl is an impact.com gateway tracking link.
          example: https://www.mysite.com/products/145324
        clickId:
          type: string
          description: The unique click ID generated by impact.com for this event.
          example: 0c22384eN-3765c5f900c2878068a0631b
        warnings:
          type: array
          description: Non-fatal warnings about the request.
          items:
            $ref: '#/components/schemas/ResponseMessage'
    PageLoadResponseDirect:
      type: object
      properties:
        clickId:
          type: string
          description: The unique click ID generated by impact.com for this event.
          example: QiiWXOVnrQ3SQHl24jQjyxBGUkmzfJ3i1VHrWM0
        sessionStart:
          type: string
          format: date-time
          description: The timestamp when the user session started.
          example: '2026-09-10T22:55:32-08:00'
        warnings:
          type: array
          description: Non-fatal warnings about the request.
          items:
            $ref: '#/components/schemas/ResponseMessage'
    ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          description: Errors that prevented the request from succeeding.
          items:
            $ref: '#/components/schemas/ResponseMessage'
        warnings:
          type: array
          description: Non-fatal warnings about the request.
          items:
            $ref: '#/components/schemas/ResponseMessage'
    ResponseMessage:
      type: object
      properties:
        field:
          type: string
          description: The request parameter that caused the message.
          example: CampaignId
        level:
          type: string
          description: The severity level of the message.
          enum:
          - ERROR
          - WARNING
        message:
          type: string
          description: A detailed explanation of the issue.
          example: Invalid campaign ID (1000)
x-default-client: cURL
