openapi: 3.1.0
info:
  title: Iterable Export Campaigns Users 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: Users
  description: Manage user profiles, update user fields, bulk update users, get user data by email or userId, and delete users.
paths:
  /users/update:
    post:
      operationId: updateUser
      summary: Update a user profile
      description: Updates an existing user profile or creates a new one if the user does not already exist. Accepts user fields, email, userId, and data fields to set or update on the user profile.
      tags:
      - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserUpdateRequest'
      responses:
        '200':
          description: Successfully updated the user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IterableResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid API key
  /users/bulkUpdate:
    post:
      operationId: bulkUpdateUsers
      summary: Bulk update user profiles
      description: Updates multiple user profiles in a single request. Each user object in the array can include email, userId, and data fields to update.
      tags:
      - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - users
              properties:
                users:
                  type: array
                  description: Array of user objects to update
                  items:
                    $ref: '#/components/schemas/UserUpdateRequest'
      responses:
        '200':
          description: Successfully queued bulk update
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IterableResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /users/{email}:
    get:
      operationId: getUserByEmail
      summary: Get a user by email
      description: Retrieves the full user profile for a given email address, including all data fields and subscription preferences.
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/emailPath'
      responses:
        '200':
          description: User profile data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: User not found
    delete:
      operationId: deleteUserByEmail
      summary: Delete a user by email
      description: Deletes a user profile identified by email address from the Iterable project.
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/emailPath'
      responses:
        '200':
          description: Successfully deleted user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IterableResponse'
        '401':
          description: Unauthorized
        '404':
          description: User not found
  /users/byUserId/{userId}:
    get:
      operationId: getUserByUserId
      summary: Get a user by userId
      description: Retrieves the full user profile for a given userId, including all data fields and subscription preferences.
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/userIdPath'
      responses:
        '200':
          description: User profile data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: User not found
    delete:
      operationId: deleteUserByUserId
      summary: Delete a user by userId
      description: Deletes a user profile identified by userId from the Iterable project.
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/userIdPath'
      responses:
        '200':
          description: Successfully deleted user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IterableResponse'
        '401':
          description: Unauthorized
        '404':
          description: User not found
  /users/getFields:
    get:
      operationId: getUserFields
      summary: Get user fields
      description: Retrieves all user field names and their data types defined in the Iterable project.
      tags:
      - Users
      responses:
        '200':
          description: List of user fields
          content:
            application/json:
              schema:
                type: object
                properties:
                  fields:
                    type: object
                    description: Map of field names to their data types
                    additionalProperties:
                      type: string
        '401':
          description: Unauthorized
  /users/registerDeviceToken:
    post:
      operationId: registerDeviceToken
      summary: Register a device token
      description: Registers a device token (APNs or FCM) for a user to enable push notification delivery.
      tags:
      - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              - device
              properties:
                email:
                  type: string
                  description: Email address of the user
                device:
                  type: object
                  description: Device token information
                  properties:
                    token:
                      type: string
                      description: The device token
                    platform:
                      type: string
                      enum:
                      - APNS
                      - APNS_SANDBOX
                      - GCM
                      description: The push platform
                    applicationName:
                      type: string
                      description: The application name
      responses:
        '200':
          description: Device token registered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IterableResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
components:
  schemas:
    UserResponse:
      type: object
      description: User profile response containing all user data
      properties:
        user:
          type: object
          properties:
            email:
              type: string
              format: email
              description: Email address
            userId:
              type: string
              description: User ID
            dataFields:
              type: object
              description: Custom user data fields
              additionalProperties: true
            signupDate:
              type: string
              format: date-time
              description: User signup date
            profileUpdatedAt:
              type: string
              format: date-time
              description: Last profile update timestamp
    IterableResponse:
      type: object
      description: Standard Iterable API response indicating success or failure
      properties:
        msg:
          type: string
          description: Human-readable response message
        code:
          type: string
          description: Response code indicating success or error type
        params:
          type: object
          description: Additional response parameters
          additionalProperties: true
    UserUpdateRequest:
      type: object
      description: Request body for updating a user profile
      properties:
        email:
          type: string
          format: email
          description: Email address of the user
        userId:
          type: string
          description: Unique user identifier
        dataFields:
          type: object
          description: Custom data fields to set on the user profile
          additionalProperties: true
        preferUserId:
          type: boolean
          description: Whether to prefer userId over email for identity resolution
        mergeNestedObjects:
          type: boolean
          description: Whether to merge nested objects or overwrite them
    ErrorResponse:
      type: object
      description: Error response returned when a request fails validation
      properties:
        msg:
          type: string
          description: Error message describing what went wrong
        code:
          type: string
          description: Error code
        params:
          type: object
          description: Additional error details
          additionalProperties: true
  parameters:
    emailPath:
      name: email
      in: path
      required: true
      description: Email address of the user
      schema:
        type: string
        format: email
    userIdPath:
      name: userId
      in: path
      required: true
      description: The userId of the user
      schema:
        type: string
  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