Iterable Workflows API

openapi: 3.2.0
info:
  title: Iterable Workflows API
  version: '1.0'
  description: 'Operations tagged workflows across 2 of this provider''s published API definitions: iterable-api-openapi.json, iterable-rest-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.iterable.com/
- url: https://api.iterable.com/api
  description: US Data Center (USDC)
- url: https://api.eu.iterable.com/api
  description: European Data Center (EDC)
tags:
- name: workflows
paths:
  /api/journeys:
    get:
      description: Get a list of the journeys within your project.
      operationId: getJourneys
      parameters:
      - description: Page number (starting at 1).
        in: query
        name: page
        required: false
        x-example: 1
        schema:
          type: integer
          format: int32
      - description: Number of results to return per page (defaults to 10, maximum of 50).
        in: query
        name: pageSize
        required: false
        x-example: 25
        schema:
          type: integer
          format: int32
      - description: 'Sort field with optional direction prefix. Use - for descending, + or no prefix for ascending. Examples: -createdAt, +name, id'
        in: query
        name: sort
        required: false
        x-example: id
        schema:
          type: string
          default: id
      - description: Without this parameter, the endpoint returns all non-archived journeys. With state set to Archived, the endpoint only returns archived journeys.
        in: query
        name: state
        required: false
        x-example: Archived
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetJourneysResponse'
        '400':
          description: Invalid parameters.
        '401':
          description: Invalid API key.
      summary: Get journeys (workflows)
      tags:
      - workflows
      security:
      - api_key: []
    servers:
    - url: https://api.iterable.com/
  /api/workflows/triggerWorkflow:
    post:
      description: Triggers a journey (formerly known as workflow). Triggering with a list is asynchronous. If a list trigger is in progress, it must finish before the same list can be triggered again for a particular journey. The journey stats may take several minutes to update if other journeys are running. If the journey's start tile has a suppression list, that will apply.<br/><br/>Learn about <a href="https://support.iterable.com/hc/articles/29156459027348">identifying users by <code>userId</code> and <code>email</code></a>.
      operationId: triggerWorkflow
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IterableApiResponse'
        '400':
          description: Invalid parameters
        '401':
          description: Invalid API key
      summary: Trigger a journey (workflow)
      tags:
      - workflows
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TriggerWorkflowRequest'
        description: Trigger workflow request
        required: true
      security:
      - api_key: []
    servers:
    - url: https://api.iterable.com/
  /workflows/triggerWorkflow:
    post:
      operationId: triggerWorkflow
      summary: Trigger a workflow
      description: Triggers a workflow enrollment for one or more users. The workflow must already be created and activated in the Iterable project.
      tags:
      - workflows
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - workflowId
              properties:
                workflowId:
                  type: integer
                  description: The ID of the workflow to trigger
                email:
                  type: string
                  description: Email address of the user to enroll
                dataFields:
                  type: object
                  description: Data fields to pass to the workflow
                  additionalProperties: true
                listId:
                  type: integer
                  description: List ID to enroll all members of a list
      responses:
        '200':
          description: Workflow triggered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IterableResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
      security:
      - apiKeyAuth: []
    servers:
    - url: https://api.iterable.com/api
      description: US Data Center (USDC)
    - url: https://api.eu.iterable.com/api
      description: European Data Center (EDC)
components:
  schemas:
    GetJourneysResponse:
      properties:
        journeys:
          description: The current page of journeys.
          items:
            $ref: '#/components/schemas/JourneyDetails'
          type: array
        nextPageUrl:
          description: The URL to the next page of journeys, if applicable.
          type: string
        previousPageUrl:
          description: The URL to the previous page of journeys, if applicable.
          type: string
        totalJourneysCount:
          description: The total count of journeys across all pages for the supplied query.
          format: int64
          type: integer
      required:
      - journeys
      - totalJourneysCount
      type: object
    TriggerWorkflowRequest:
      properties:
        dataFields:
          description: Additional data associated triggering event
          type: object
        email:
          description: An email address that identifies a user profile in Iterable. Provide an <code>email</code> or a <code>userId</code> (but not both), depending on <a href="https://support.iterable.com/hc/articles/29156459027348">how your project identifies users</a>.
          type: string
        listId:
          description: (Optional) Trigger the journey for all users in a list (standard or dynamic)
          format: int32
          type: integer
        userId:
          description: A user ID that identifies a user profile in Iterable. Provide an <code>email</code> or a <code>userId</code> (but not both), depending on <a href="https://support.iterable.com/hc/articles/29156459027348">how your project identifies users</a>.
          type: string
        workflowId:
          description: ID of journey (workflow) to trigger
          format: int64
          type: integer
      required:
      - workflowId
      type: object
    IterableApiResponse:
      properties:
        code:
          enum:
          - Success
          - BadApiKey
          - BadAuthorizationHeader
          - BadJsonBody
          - BadParams
          - BatchTooLarge
          - DatabaseError
          - EmailAlreadyExists
          - ExternalKeyConflict
          - Forbidden
          - ForbiddenParamsError
          - ForgottenUserError
          - GenericError
          - InvalidEmailAddressError
          - InvalidJwtPayload
          - InvalidUserIdError
          - JwtUserIdentifiersMismatched
          - NotFound
          - QueueEmailError
          - RateLimitExceeded
          - RequestFieldsTypesMismatched
          - Unauthorized
          - UniqueFieldsLimitExceeded
          - UnknownEmailError
          - UnknownUserIdError
          - UserIdAlreadyExists
          type: string
        msg:
          description: Response description
          type: string
        params:
          description: Additional info
          type: object
      required:
      - code
      - msg
      type: object
    JourneyDraftDetails:
      properties:
        createdAt:
          description: Creation timestamp as epoch time in milliseconds.
          format: int32
          type: integer
        creatorUserId:
          description: The email address of the user who created the draft journey.
          type: string
        id:
          description: The unique identifier for the draft journey.
          type: number
        name:
          description: The name of the draft journey.
          type: string
        updatedAt:
          description: Last update timestamp as epoch time in milliseconds.
          format: int32
          type: integer
      required:
      - createdAt
      - creatorUserId
      - id
      - name
      - updatedAt
      type: object
    JourneyDetails:
      properties:
        createdAt:
          description: Creation timestamp as epoch time in milliseconds.
          format: int32
          type: integer
        creatorUserId:
          description: The email address of the user who created the draft journey.
          type: string
        description:
          description: A description of the journey.
          type: string
        draft:
          $ref: '#/components/schemas/JourneyDraftDetails'
          description: If a published journey has an active draft, this object will describe that draft.
        enabled:
          description: <code>true</code> if the journey is currently accepting new user entrances.
          type: boolean
        id:
          type: number
        isArchived:
          description: <code>true</code> if the journey is archived.
          type: boolean
        journeyType:
          description: Whether the journey is published or a draft.
          type: string
        lifetimeLimit:
          description: The number of times a user can enter a journey in their lifetime.
          format: int32
          type: integer
        name:
          description: The name of the journey.
          type: string
        simultaneousLimit:
          description: The number of times a user can be in a journey simultaneously.
          format: int32
          type: integer
        startTileId:
          description: The ID of the start tile of the journey.
          format: int32
          type: integer
        triggerEventNames:
          description: The names of the events responsible for triggering users into the journey, if applicable.
          items:
            type: string
          type: array
        updatedAt:
          description: Last update timestamp as epoch time in milliseconds.
          format: int32
          type: integer
      type: object
    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
  securitySchemes:
    api_key:
      in: header
      name: Api-Key
      type: apiKey
    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 Documentation
  url: https://api.iterable.com/api/docs
x-refined-from:
- iterable-api-openapi.json
- iterable-rest-api-openapi.yml