Skai (Kenshoo) Bulk Update API

openapi: 3.2.0
info:
  title: Skai Bulk Update API
  description: '# Overview

    Skai APIs provide programmatic access to advertising data and campaign management across Search, Social, and Retail Media publishers.'
  version: 1.0.0
  x-logo:
    url: https://grid.kenshoo.com/resources-frontend/latest/kenshoo_logo/skai-logo-devportal.svg
    backgroundColor: '#FFFFFF'
    altText: Skai
servers:
- url: https://services.kenshoo.com
security:
- BearerAuth: []
tags:
- name: Bulk Update
  description: 'Publishers:

    Search

    Social (excl. Meta)

    Retail Media'
paths:
  /api/v1/bulk_update:
    post:
      tags:
      - Bulk Update
      summary: Make bulk changes to multiple entities
      description: Upload a CSV bulksheet to create and update campaigns, ad groups, keywords, ads, and more — across dozens of publishers — in a single API call.
      operationId: bulkUpdate
      parameters:
      - $ref: '#/components/parameters/ks'
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  description: CSV, XLSX, TXT, or TSV — uncompressed or zip-compressed. Maximum size 50 MB.
                  format: binary
                file_delimiter:
                  type: string
                  description: Column delimiter used in the file. Use `COMMA` for standard CSV.
                  enum:
                  - COMMA
                  - TAB
                  - SEMICOLON
                bulk_update_type:
                  type: string
                  description: The entity type of the uploaded file. Use `MULTI_ENTITY_FILE` (recommended) to mix entity types in one file using an `Entity Type` column. Use a specific entity type for single-entity files.
                  enum:
                  - MULTI_ENTITY_FILE
                  - CAMPAIGN
                  - AD_GROUP
                  - KEYWORD
                  - AD
                  - PRODUCT_GROUP
                  - PORTFOLIO
                  - SITELINK
                  - AUDIENCES
                  - PROFILE_STATUS
                  - PROFILE_F2A
                  - PROFILE_ONBOARDING
        required: true
      responses:
        200:
          description: Job created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  job_id:
                    type: string
                    description: Use this ID to poll job status and retrieve results.
              example:
                job_id: c42f1168-4cd6-42e8-b654-2a7f0043699e
        400:
          $ref: '#/components/responses/BadRequest'
        500:
          $ref: '#/components/responses/InternalServerError'
      x-code-samples:
      - lang: cURL
        source: "curl -X POST \\\n  'https://services.kenshoo.com/api/v1/bulk_update?ks=<YOUR_KS_ID>' \\\n  -H 'Authorization: Bearer <YOUR_TOKEN>' \\\n  -F 'file=@changes.csv' \\\n  -F 'file_delimiter=COMMA' \\\n  -F 'bulk_update_type=MULTI_ENTITY_FILE'\n\n# Response: {\"job_id\": \"c42f1168-4cd6-42e8-b654-2a7f0043699e\"}\n# Then poll: GET /api/v1/jobs/{job_id}/status\n"
components:
  schemas:
    ApiResponseStatus:
      type: string
      readOnly: true
      enum:
      - SUCCESS
      - FAILED
      - PARTIAL_SUCCESS
    ApiResponse:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/ApiResponseStatus'
        entities:
          type: array
          items:
            $ref: '#/components/schemas/EntityResponse'
    EntityResponse:
      type: object
      properties:
        id:
          type: integer
          format: int64
        success:
          type: boolean
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorField'
    ErrorField:
      type: object
      properties:
        fieldName:
          type: string
          description: The error field
        error:
          type: string
          description: Error message
        parameters:
          type: object
          additionalProperties:
            type: string
          description: Error additional properties
  responses:
    BadRequest:
      description: Bad request (usually indicates validation failure for client input)
      content:
        application/json:
          schema:
            $ref: '#/components/responses/ApiResponse'
          example:
            status: FAILED
            entities:
            - id: null
              success: false
              errors:
              - field_name: name
                error: ILLEGAL_NAME
    InternalServerError:
      description: Server error
      content:
        application/json:
          schema:
            $ref: '#/components/responses/ApiResponse'
          example:
            status: FAILED
            entities:
            - id: null
              success: false
              errors:
              - field_name: ServerError
                error: Unexpected error occurred.
                parameters: {}
    ApiResponse:
      $ref: '#/components/schemas/ApiResponse'
  parameters:
    ks:
      name: ks
      in: query
      description: The KS to refer the request to. You can find this ID in the Skai platform under _Administration_ -> _About Skai_ -> _Server ID_
      required: true
      style: form
      explode: true
      schema:
        type: string
      example: '1234'
x-tagGroups:
- name: Reporting
  tags:
  - Available Columns
  - Synchronous Reports
  - Asynchronous Reports
- name: Bulk Operations
  tags:
  - Jobs
  - Bulk Update
- name: AI & MCP
  tags:
  - MCP
- name: Objects
  tags:
  - Profile
  - Campaigns
  - Ad Groups
  - Ads
  - Product Groups
  - Portfolios
  - Meta Campaigns
  - Meta Ad Groups
  - Meta Ads
  - Columns