Iterable Users API
Manage user profiles, update user fields, bulk update users, get user data by email or userId, and delete users.
OpenAPI Specification
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