Iterable Export API

openapi: 3.1.0
info:
  title: Iterable Campaigns Export API
  description: The Iterable Export API enables developers to extract data from Iterable projects for analytics, reporting, and data warehousing purposes. It provides export endpoints that allow retrieval of user data, event data, campaign metrics, and message engagement information in CSV and JSON formats. The export endpoints support filtering by date ranges and event types, making it possible to build custom reporting pipelines and synchronize Iterable data with external business intelligence tools.
  version: 1.0.0
  contact:
    name: Iterable Support
    url: https://support.iterable.com
  termsOfService: https://iterable.com/trust/terms-of-service
servers:
- url: https://api.iterable.com/api
  description: US Data Center (USDC)
- url: https://api.eu.iterable.com/api
  description: European Data Center (EDC)
security:
- apiKeyAuth: []
tags:
- name: Export
  description: Endpoints for exporting data from Iterable projects in CSV and JSON formats. Supports exporting user events, message engagement data, and campaign metrics.
paths:
  /export/data.json:
    get:
      operationId: exportDataJson
      summary: Export data as JSON
      description: Exports event data from the Iterable project in JSON format. Supports filtering by date range and data type. The response is a stream of newline-delimited JSON objects, each representing a single event record.
      tags:
      - Export
      parameters:
      - $ref: '#/components/parameters/dataTypeName'
      - $ref: '#/components/parameters/startDateTime'
      - $ref: '#/components/parameters/endDateTime'
      - $ref: '#/components/parameters/range'
      - $ref: '#/components/parameters/omitFields'
      - $ref: '#/components/parameters/onlyFields'
      responses:
        '200':
          description: Newline-delimited JSON export of event data
          content:
            application/x-ndjson:
              schema:
                type: string
                description: Stream of newline-delimited JSON objects
        '400':
          description: Bad request - invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid API key
  /export/data.csv:
    get:
      operationId: exportDataCsv
      summary: Export data as CSV
      description: Exports event data from the Iterable project in CSV format. Supports filtering by date range and data type. The response is a CSV file with headers in the first row.
      tags:
      - Export
      parameters:
      - $ref: '#/components/parameters/dataTypeName'
      - $ref: '#/components/parameters/startDateTime'
      - $ref: '#/components/parameters/endDateTime'
      - $ref: '#/components/parameters/range'
      - $ref: '#/components/parameters/omitFields'
      - $ref: '#/components/parameters/onlyFields'
      responses:
        '200':
          description: CSV export of event data
          content:
            text/csv:
              schema:
                type: string
                description: CSV formatted export data with headers
        '400':
          description: Bad request - invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid API key
  /export/userEvents:
    get:
      operationId: exportUserEvents
      summary: Export events for a specific user
      description: Exports all tracked events for a specific user identified by email address. Returns events in JSON format with support for pagination and filtering by event type.
      tags:
      - Export
      parameters:
      - name: email
        in: query
        required: true
        description: Email address of the user whose events to export
        schema:
          type: string
          format: email
      - name: includeCustomEvents
        in: query
        description: Whether to include custom events in the export
        schema:
          type: boolean
          default: true
      responses:
        '200':
          description: User events data
          content:
            application/json:
              schema:
                type: object
                properties:
                  events:
                    type: array
                    description: Array of events tracked for the user
                    items:
                      $ref: '#/components/schemas/ExportedEvent'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: User not found
components:
  schemas:
    ExportedEvent:
      type: object
      description: An exported event record
      properties:
        email:
          type: string
          format: email
          description: Email address of the user
        eventName:
          type: string
          description: Name of the event
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the event was created
        campaignId:
          type: integer
          description: Associated campaign ID if applicable
        templateId:
          type: integer
          description: Associated template ID if applicable
        messageId:
          type: string
          description: Unique message ID for sent messages
        dataFields:
          type: object
          description: Additional event data fields
          additionalProperties: true
        contentId:
          type: integer
          description: Content ID for experiments
        channelId:
          type: integer
          description: Channel ID for the message
        messageTypeId:
          type: integer
          description: Message type ID
        workflowId:
          type: integer
          description: Workflow ID if the event was triggered by a workflow
        workflowName:
          type: string
          description: Name of the associated workflow
        campaignName:
          type: string
          description: Name of the associated campaign
        templateName:
          type: string
          description: Name of the associated template
        labels:
          type: array
          description: Labels associated with the campaign
          items:
            type: string
    ErrorResponse:
      type: object
      description: Error response returned when a request fails
      properties:
        msg:
          type: string
          description: Error message describing what went wrong
        code:
          type: string
          description: Error code
  parameters:
    onlyFields:
      name: onlyFields
      in: query
      description: Comma-separated list of fields to include in the export. When specified, only these fields are returned.
      schema:
        type: string
    range:
      name: range
      in: query
      description: Predefined date range to export. Use instead of startDateTime and endDateTime for convenience. Options include Today, Yesterday, BeforeToday, and All.
      schema:
        type: string
        enum:
        - Today
        - Yesterday
        - BeforeToday
        - All
    omitFields:
      name: omitFields
      in: query
      description: Comma-separated list of fields to exclude from the export
      schema:
        type: string
    endDateTime:
      name: endDateTime
      in: query
      description: End of the export date range in ISO 8601 format (e.g., 2024-01-31T23:59:59Z)
      schema:
        type: string
        format: date-time
    dataTypeName:
      name: dataTypeName
      in: query
      required: true
      description: The type of data to export. Supported types include emailSend, emailOpen, emailClick, emailUnSubscribe, emailBounce, emailComplaint, pushSend, pushBounce, pushOpen, smsSend, smsBounce, smsReceived, inAppSend, inAppOpen, inAppClick, webPushSend, purchase, customEvent, and hostedUnsubscribeClick.
      schema:
        type: string
        enum:
        - emailSend
        - emailOpen
        - emailClick
        - emailUnSubscribe
        - emailBounce
        - emailComplaint
        - pushSend
        - pushBounce
        - pushOpen
        - smsSend
        - smsBounce
        - smsReceived
        - inAppSend
        - inAppOpen
        - inAppClick
        - webPushSend
        - purchase
        - customEvent
        - hostedUnsubscribeClick
        - userNew
        - userUpdate
    startDateTime:
      name: startDateTime
      in: query
      description: Start of the export date range in ISO 8601 format (e.g., 2024-01-01T00:00:00Z)
      schema:
        type: string
        format: date-time
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Api-Key
      description: Iterable API key passed in the Api-Key header. API keys can be created and managed in the Iterable project settings.
externalDocs:
  description: Iterable API Endpoints and Sample Payloads
  url: https://support.iterable.com/hc/en-us/articles/204780579-Iterable-API-Endpoints-and-Sample-Payloads