openapi: 3.1.0
info:
  title: Brand Exception Lists API
  version: v11
  description: "Manage Exception Lists to pay partners different rates based on Category or SKU. \nThis API allows for the management of the lists themselves and the individual items/rules within them.\n"
servers:
- url: https://api.impact.com
security:
- basicAuth: []
paths:
  /Advertisers/{AccountSID}/ExceptionLists:
    get:
      operationId: listExceptionLists
      tags:
      - Exception Lists
      summary: List all exception lists
      parameters:
      - name: AccountSID
        in: path
        required: true
        description: The unique identifier for the account.
        schema:
          type: string
      - name: CampaignId
        in: query
        description: Filter by the program ID the list applies to.
        schema:
          type: integer
      - name: State
        in: query
        description: Filter lists by their current state.
        schema:
          type: string
          enum:
          - ACTIVE
          - CLOSED
          - DEACTIVATED
      - name: Type
        in: query
        description: Filter lists by whether they apply to CATEGORY or SKU.
        schema:
          type: string
          enum:
          - CATEGORY
          - SKU
      responses:
        '200':
          description: A list of exception list objects.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ExceptionLists:
                    type: array
                    description: The list of exception list objects.
                    items:
                      $ref: '#/components/schemas/ExceptionList'
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -L \
            --url 'https://api.impact.com/Advertisers/{AccountSID}/ExceptionLists' \
            --user '{AccountSID}:{AuthToken}' \
            --header 'Accept: */*'
    post:
      operationId: createExceptionList
      tags:
      - Exception Lists
      summary: Create an exception list
      parameters:
      - name: AccountSID
        in: path
        required: true
        description: The unique identifier for the account.
        schema:
          type: string
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - ActionTrackerId
              - CampaignId
              - Name
              - Type
              properties:
                ActionTrackerId:
                  type: string
                  description: Comma-separated list of event type IDs.
                  example: '18500'
                CampaignId:
                  type: integer
                  description: The program ID the list applies to.
                  example: 1000
                Name:
                  type: string
                  description: The display name for the exception list.
                  example: USA-State-CA-Exclusions
                Type:
                  type: string
                  description: Whether this list applies to CATEGORY or SKU.
                  enum:
                  - CATEGORY
                  - SKU
      responses:
        '200':
          description: The exception list was created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusUriResponse'
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -L \
            --request POST \
            --url 'https://api.impact.com/Advertisers/{AccountSID}/ExceptionLists' \
            --user '{AccountSID}:{AuthToken}' \
            --header 'Content-Type: application/x-www-form-urlencoded' \
            --header 'Accept: */*'
  /Advertisers/{AccountSID}/ExceptionLists/{ExceptionListId}:
    get:
      operationId: getExceptionList
      tags:
      - Exception Lists
      summary: Retrieve an exception list
      parameters:
      - name: AccountSID
        in: path
        required: true
        description: The unique identifier for the account.
        schema:
          type: string
      - name: ExceptionListId
        in: path
        required: true
        description: The unique identifier for the exception list.
        schema:
          type: integer
      responses:
        '200':
          description: A single exception list object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionList'
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -L \
            --url 'https://api.impact.com/Advertisers/{AccountSID}/ExceptionLists/{ExceptionListId}' \
            --user '{AccountSID}:{AuthToken}' \
            --header 'Accept: */*'
    put:
      operationId: updateExceptionList
      tags:
      - Exception Lists
      summary: Update an exception list
      parameters:
      - name: AccountSID
        in: path
        required: true
        description: The unique identifier for the account.
        schema:
          type: string
      - name: ExceptionListId
        in: path
        required: true
        description: The unique identifier for the exception list to update.
        schema:
          type: integer
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                ActionTrackerId:
                  type: string
                  description: Comma-separated list of event type IDs.
                  example: '18500'
                Name:
                  type: string
                  description: The display name for the exception list.
                  example: USA-State-CA-Exclusions
                Type:
                  type: string
                  description: Whether this list applies to CATEGORY or SKU.
                  enum:
                  - CATEGORY
                  - SKU
      responses:
        '200':
          description: The exception list was updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusUriResponse'
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -L \
            --request PUT \
            --url 'https://api.impact.com/Advertisers/{AccountSID}/ExceptionLists/{ExceptionListId}' \
            --user '{AccountSID}:{AuthToken}' \
            --header 'Content-Type: application/x-www-form-urlencoded' \
            --header 'Accept: */*'
  /Advertisers/{AccountSID}/ExceptionLists/{ExceptionListId}/Items:
    get:
      operationId: listExceptionListItems
      tags:
      - Exception List Items
      summary: List all items for an exception list
      parameters:
      - name: AccountSID
        in: path
        required: true
        description: The unique identifier for the account.
        schema:
          type: string
      - name: ExceptionListId
        in: path
        required: true
        description: The unique identifier for the exception list.
        schema:
          type: integer
      - name: Value
        in: query
        description: Filter items by their 'Value' (the SKU or Category).
        schema:
          type: string
      responses:
        '200':
          description: A list of exception list item objects.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ExceptionListItems:
                    type: array
                    description: The list of items in this exception list.
                    items:
                      $ref: '#/components/schemas/ExceptionListItem'
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -L \
            --url 'https://api.impact.com/Advertisers/{AccountSID}/ExceptionLists/{ExceptionListId}/Items' \
            --user '{AccountSID}:{AuthToken}' \
            --header 'Accept: */*'
    post:
      operationId: createExceptionListItem
      tags:
      - Exception List Items
      summary: Create an item for an exception list
      description: Create an item manually or via CSV/XLSX file upload.
      parameters:
      - name: AccountSID
        in: path
        required: true
        description: The unique identifier for the account.
        schema:
          type: string
      - name: ExceptionListId
        in: path
        required: true
        description: The unique identifier for the exception list.
        schema:
          type: integer
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - Value
              properties:
                Value:
                  type: string
                  description: The CATEGORY or SKU value.
                  example: CA
                Name:
                  type: string
                  description: Display name for the item.
                  example: California
                Upsert:
                  type: boolean
                  description: If true, updates an existing item with the same 'Value'.
                  example: true
          multipart/form-data:
            schema:
              type: object
              properties:
                File:
                  type: string
                  format: binary
                  description: A .CSV or .XLSX file containing the items to add.
                Upsert:
                  type: boolean
                  description: If true, updates existing items where 'Value' matches.
                  example: true
        description: "To create a single item, send `Value` (and optionally `Name`) as `application/x-www-form-urlencoded`.\n\nTo bulk-upload items from a `.csv` or `.xlsx` file, switch the content type to `multipart/form-data` and send the `File` parameter."
      responses:
        '200':
          description: The item(s) were created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusUriResponse'
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -L \
            --request POST \
            --url 'https://api.impact.com/Advertisers/{AccountSID}/ExceptionLists/{ExceptionListId}/Items' \
            --user '{AccountSID}:{AuthToken}' \
            --header 'Content-Type: application/x-www-form-urlencoded' \
            --header 'Accept: */*'
    patch:
      operationId: replaceExceptionListItems
      tags:
      - Exception List Items
      summary: Replace all items in an exception list
      description: Replaces items by uploading a .CSV or .XLSX file.
      parameters:
      - name: AccountSID
        in: path
        required: true
        description: The unique identifier for the account.
        schema:
          type: string
      - name: ExceptionListId
        in: path
        required: true
        description: The unique identifier for the exception list.
        schema:
          type: integer
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - File
              properties:
                File:
                  type: string
                  format: binary
                  description: A .CSV or .XLSX file containing the new items.
      responses:
        '200':
          description: The items were replaced successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusUriResponse'
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -L \
            --request PATCH \
            --url 'https://api.impact.com/Advertisers/{AccountSID}/ExceptionLists/{ExceptionListId}/Items' \
            --user '{AccountSID}:{AuthToken}' \
            --header 'Accept: */*'
    delete:
      operationId: deleteAllExceptionListItems
      tags:
      - Exception List Items
      summary: Delete all items in an exception list
      parameters:
      - name: AccountSID
        in: path
        required: true
        description: The unique identifier for the account.
        schema:
          type: string
      - name: ExceptionListId
        in: path
        required: true
        description: The unique identifier for the exception list.
        schema:
          type: integer
      responses:
        '200':
          description: All items were deleted successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Status:
                    type: string
                    description: Indicates that the items were deleted.
                    example: DELETED
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -L \
            --request DELETE \
            --url 'https://api.impact.com/Advertisers/{AccountSID}/ExceptionLists/{ExceptionListId}/Items' \
            --user '{AccountSID}:{AuthToken}' \
            --header 'Accept: */*'
  /Advertisers/{AccountSID}/ExceptionLists/{ExceptionListId}/Items/{ItemId}:
    get:
      operationId: getExceptionListItem
      tags:
      - Exception List Items
      summary: Retrieve an exception list item
      parameters:
      - name: AccountSID
        in: path
        required: true
        description: The unique identifier for the account.
        schema:
          type: string
      - name: ExceptionListId
        in: path
        required: true
        description: The unique identifier for the exception list.
        schema:
          type: integer
      - name: ItemId
        in: path
        required: true
        description: The unique identifier for the exception list item.
        schema:
          type: integer
      responses:
        '200':
          description: A single exception list item object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionListItem'
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -L \
            --url 'https://api.impact.com/Advertisers/{AccountSID}/ExceptionLists/{ExceptionListId}/Items/{ItemId}' \
            --user '{AccountSID}:{AuthToken}' \
            --header 'Accept: */*'
    delete:
      operationId: deleteExceptionListItem
      tags:
      - Exception List Items
      summary: Delete an item for an exception list
      parameters:
      - name: AccountSID
        in: path
        required: true
        description: The unique identifier for the account.
        schema:
          type: string
      - name: ExceptionListId
        in: path
        required: true
        description: The unique identifier for the exception list.
        schema:
          type: integer
      - name: ItemId
        in: path
        required: true
        description: The unique identifier for the exception list item.
        schema:
          type: integer
      responses:
        '200':
          description: The item was deleted successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Status:
                    type: string
                    description: Indicates that the item was deleted.
                    example: DELETED
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -L \
            --request DELETE \
            --url 'https://api.impact.com/Advertisers/{AccountSID}/ExceptionLists/{ExceptionListId}/Items/{ItemId}' \
            --user '{AccountSID}:{AuthToken}' \
            --header 'Accept: */*'
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
  schemas:
    ExceptionList:
      type: object
      properties:
        Id:
          type: integer
          description: The unique identifier for the exception list.
          example: 99999
        Name:
          type: string
          description: The display name for the exception list.
          example: USA-State-CA-Exclusions
        State:
          type: string
          description: The current state of the exception list.
          enum:
          - ACTIVE
          - CLOSED
          - DEACTIVATED
        CampaignId:
          type: integer
          description: The program ID the list applies to.
          example: 1000
        Type:
          type: string
          description: Whether the list applies to CATEGORY or SKU.
          enum:
          - CATEGORY
          - SKU
        CreatedDate:
          type: string
          format: date-time
          description: The date and time the list was created.
          example: '2026-01-15T10:00:00-08:00'
        DeactivationDate:
          type: string
          format: date-time
          nullable: true
          description: The date and time the list was deactivated, if applicable.
          example: '2026-12-31T23:59:59-08:00'
        ActionTrackers:
          type: array
          description: The action trackers (event types) this list applies to.
          items:
            type: object
            properties:
              Id:
                type: integer
                description: The unique identifier for the action tracker.
                example: 18500
              Name:
                type: string
                description: The display name of the action tracker.
                example: Online Sale
        NumberOfItems:
          type: integer
          description: The total number of items in the list.
          example: 50
        ItemsUri:
          type: string
          format: uri-reference
          description: The unique reference to the items collection for this list.
          example: /Advertisers/<AccountSID>/ExceptionLists/99999/Items
        Uri:
          type: string
          format: uri-reference
          description: The unique reference to this exception list in the impact.com API.
          example: /Advertisers/<AccountSID>/ExceptionLists/12345
    ExceptionListItem:
      type: object
      properties:
        Id:
          type: integer
          description: The unique identifier for the exception list item.
          example: 1001
        Value:
          type: string
          description: The CATEGORY or SKU value.
          example: CA
        Name:
          type: string
          description: Display name for the item.
          example: California
        MatchMode:
          type: string
          description: How the value is matched against incoming actions.
          enum:
          - EQ
          - REGEX
        ListId:
          type: integer
          description: The unique identifier of the parent exception list.
          example: 99999
        CreatedDate:
          type: string
          format: date-time
          description: The date and time the item was created.
          example: '2026-01-15T10:00:00-08:00'
        Uri:
          type: string
          format: uri-reference
          description: The unique reference to this item in the impact.com API.
    StatusUriResponse:
      type: object
      properties:
        Status:
          type: string
          description: Indicates whether the operation was successful.
        Uri:
          type: string
          format: uri-reference
          description: The unique reference to the affected resource.
x-default-client: cURL
