Salesforce Marketing Cloud Journeys API

openapi: 3.2.0
info:
  title: Salesforce Marketing Cloud REST Journeys API
  description: The Salesforce Marketing Cloud REST API provides programmatic access to Marketing Cloud features including contacts, journeys, and assets. The API uses JSON request and response bodies and OAuth 2.0 authentication via the Marketing Cloud authentication endpoint. All API requests require a valid access token obtained through the Server-to-Server OAuth flow.
  version: 1.0.0
  termsOfService: https://www.salesforce.com/company/legal/
  contact:
    name: Salesforce Marketing Cloud Support
    url: https://help.salesforce.com/s/
    email: support@salesforce.com
  license:
    name: Salesforce Master Subscription Agreement
    url: https://www.salesforce.com/company/legal/agreements/
servers:
- url: https://{subdomain}.rest.marketingcloudapis.com
  description: Marketing Cloud REST API endpoint
  variables:
    subdomain:
      default: YOUR_SUBDOMAIN
      description: Your Marketing Cloud tenant-specific subdomain (e.g., mc563885gzs27c5t9-63k636ttgm). Obtain this from Setup > Apps > Installed Packages in Marketing Cloud.
security:
- OAuth2: []
tags:
- name: Journeys
  description: Create, manage, and automate customer journeys across multiple channels and touchpoints. Journeys define the automated workflows that guide customers through marketing interactions.
  externalDocs:
    description: Journey Builder API Documentation
    url: https://developer.salesforce.com/docs/marketing/marketing-cloud/guide/journey-builder-api-overview.html
paths:
  /interaction/v1/interactions:
    get:
      operationId: listJourneys
      summary: Salesforce Marketing Cloud List Journeys
      description: Retrieves a collection of journeys. Supports pagination through page and pageSize parameters. Returns journey definitions including their current status, version, and configuration.
      tags:
      - Journeys
      parameters:
      - name: $page
        in: query
        description: Page number for pagination (1-based)
        schema:
          type: integer
          default: 1
          minimum: 1
      - name: $pageSize
        in: query
        description: Number of journeys per page
        schema:
          type: integer
          default: 50
          minimum: 1
          maximum: 200
      - name: $orderBy
        in: query
        description: Field to sort results by (e.g., ModifiedDate DESC, Name ASC)
        schema:
          type: string
      - name: status
        in: query
        description: Filter journeys by status (Draft, Published, ScheduledToPublish, Stopped, Unpublished)
        schema:
          type: string
          enum:
          - Draft
          - Published
          - ScheduledToPublish
          - Stopped
          - Unpublished
      - name: nameOrDescription
        in: query
        description: Filter journeys by name or description (partial match)
        schema:
          type: string
      responses:
        '200':
          description: Journeys retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JourneyCollection'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createJourney
      summary: Salesforce Marketing Cloud Create a Journey
      description: Creates a new journey in Marketing Cloud. The journey specification defines the entry event, activities, triggers, and overall workflow. Journeys are created in Draft status by default and must be published to become active.
      tags:
      - Journeys
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JourneyDefinition'
            example:
              name: Welcome Journey
              description: Onboarding journey for new subscribers
              key: welcome-journey-001
              workflowApiVersion: 1.0
              triggers:
              - key: event-trigger
                name: api-event
                type: APIEvent
                eventDefinitionKey: APIEvent-welcome
              activities:
              - key: send-welcome-email
                name: Send Welcome Email
                type: EMAILV2
                configurationArguments:
                  triggeredSend:
                    emailId: 12345
      responses:
        '201':
          description: Journey created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Journey'
        '400':
          description: Bad request - invalid journey specification
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /interaction/v1/interactions/{id}:
    get:
      operationId: getJourney
      summary: Salesforce Marketing Cloud Retrieve a Journey
      description: Retrieves a single journey by its unique identifier. Returns the complete journey specification including activities, triggers, goals, and exit criteria.
      tags:
      - Journeys
      parameters:
      - name: id
        in: path
        required: true
        description: Unique identifier (UUID) of the journey
        schema:
          type: string
          format: uuid
      - name: versionNumber
        in: query
        description: Specific version number to retrieve. If omitted, returns the latest version.
        schema:
          type: integer
      responses:
        '200':
          description: Journey retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Journey'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Journey not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: updateJourney
      summary: Salesforce Marketing Cloud Update a Journey
      description: Updates an existing journey. Only journeys in Draft status can be fully updated. Published journeys support limited modifications. Provide the complete journey specification including all activities and triggers.
      tags:
      - Journeys
      parameters:
      - name: id
        in: path
        required: true
        description: Unique identifier (UUID) of the journey
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JourneyDefinition'
      responses:
        '200':
          description: Journey updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Journey'
        '400':
          description: Bad request - invalid journey specification
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Journey not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict - journey is in a non-editable state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteJourney
      summary: Salesforce Marketing Cloud Delete a Journey
      description: Deletes a journey. Only journeys in Draft or Stopped status can be deleted. Published journeys must first be stopped before deletion.
      tags:
      - Journeys
      parameters:
      - name: id
        in: path
        required: true
        description: Unique identifier (UUID) of the journey
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Journey deleted successfully
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Journey not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict - journey cannot be deleted in current state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /interaction/v1/interactions/publishAsync/{id}:
    post:
      operationId: publishJourney
      summary: Salesforce Marketing Cloud Publish a Journey
      description: Publishes a journey asynchronously, activating it for customer entry. Once published, contacts matching the entry criteria begin entering the journey. The publish operation returns a statusId for tracking progress.
      tags:
      - Journeys
      parameters:
      - name: id
        in: path
        required: true
        description: Unique identifier (UUID) of the journey to publish
        schema:
          type: string
          format: uuid
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                versionNumber:
                  type: integer
                  description: Version number to publish
      responses:
        '202':
          description: Publish operation initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublishResponse'
        '400':
          description: Bad request - journey not in publishable state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Journey not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /interaction/v1/interactions/stop/{id}:
    post:
      operationId: stopJourney
      summary: Salesforce Marketing Cloud Stop a Journey
      description: Stops a published journey. Contacts currently in the journey can either complete their current activity or be ejected immediately based on the stop configuration.
      tags:
      - Journeys
      parameters:
      - name: id
        in: path
        required: true
        description: Unique identifier (UUID) of the journey to stop
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Journey stopped successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Journey'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Journey not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict - journey is not in a stoppable state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /interaction/v1/events:
    post:
      operationId: fireEntryEvent
      summary: Salesforce Marketing Cloud Fire a Journey Entry Event
      description: Fires an entry event to inject a contact into a journey. The contact is identified by ContactKey and enters the journey associated with the specified EventDefinitionKey. Additional data can be passed as part of the event payload.
      tags:
      - Journeys
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntryEvent'
            example:
              ContactKey: example-contact-001
              EventDefinitionKey: APIEvent-welcome
              Data:
                FirstName: Jane
                LastName: Smith
                EmailAddress: jane.smith@example.com
      responses:
        '201':
          description: Event fired successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntryEventResponse'
        '400':
          description: Bad request - invalid event data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    JourneyExit:
      type: object
      description: Exit criteria that remove contacts from the journey
      properties:
        key:
          type: string
          example: example_value
        name:
          type: string
          example: Example Title
        criteria:
          type: string
          description: Criteria expression that triggers journey exit
          example: example_value
    ErrorResponse:
      type: object
      description: Standard error response returned by the Marketing Cloud API
      properties:
        message:
          type: string
          description: Human-readable error message
          example: example_value
        errorcode:
          type: integer
          description: Numeric error code
          example: 10
        documentation:
          type: string
          description: URL to relevant documentation for this error
          example: example_value
    JourneyGoal:
      type: object
      description: Goal criteria for measuring journey success
      properties:
        key:
          type: string
          example: example_value
        name:
          type: string
          example: Example Title
        description:
          type: string
          example: A sample description.
        metCriteria:
          type: string
          description: Criteria expression that defines when the goal is met
          example: example_value
    Journey:
      type: object
      description: Represents a customer journey in Marketing Cloud. A journey defines an automated workflow that guides contacts through a series of marketing interactions across channels.
      properties:
        id:
          type: string
          format: uuid
          description: System-generated unique identifier for the journey
          example: abc123
        key:
          type: string
          description: Customer-defined unique key for the journey
          example: example_value
        name:
          type: string
          description: Display name of the journey
          example: Example Title
        description:
          type: string
          description: Description of the journey purpose
          example: A sample description.
        version:
          type: integer
          description: Current version number of the journey
          example: 10
        status:
          type: string
          description: Current status of the journey
          enum:
          - Draft
          - Published
          - ScheduledToPublish
          - Stopped
          - Unpublished
          example: Draft
        createdDate:
          type: string
          format: date-time
          example: '2026-01-15T10:30:00Z'
        modifiedDate:
          type: string
          format: date-time
          example: '2026-01-15T10:30:00Z'
        workflowApiVersion:
          type: number
          description: Version of the Journey Builder API used
          example: 42.5
        triggers:
          type: array
          description: Entry triggers that inject contacts into the journey
          items:
            $ref: '#/components/schemas/JourneyTrigger'
          example: []
        activities:
          type: array
          description: Activities that contacts pass through in the journey
          items:
            $ref: '#/components/schemas/JourneyActivity'
          example: []
        goals:
          type: array
          description: Goal criteria that measure journey success
          items:
            $ref: '#/components/schemas/JourneyGoal'
          example: []
        exits:
          type: array
          description: Exit criteria that remove contacts from the journey
          items:
            $ref: '#/components/schemas/JourneyExit'
          example: []
        stats:
          type: object
          description: Runtime statistics for the journey
          properties:
            currentPopulation:
              type: integer
              description: Number of contacts currently in the journey
            cumulativePopulation:
              type: integer
              description: Total contacts that have entered the journey
            metGoal:
              type: integer
              description: Number of contacts that met the journey goal
          example: example_value
    JourneyDefinition:
      type: object
      description: Specification for creating or updating a journey
      properties:
        key:
          type: string
          description: Customer-defined unique key for the journey
          example: example_value
        name:
          type: string
          description: Display name of the journey
          example: Example Title
        description:
          type: string
          description: Description of the journey purpose
          example: A sample description.
        workflowApiVersion:
          type: number
          description: Version of the Journey Builder API (e.g., 1.0)
          example: 42.5
        triggers:
          type: array
          items:
            $ref: '#/components/schemas/JourneyTrigger'
          example: []
        activities:
          type: array
          items:
            $ref: '#/components/schemas/JourneyActivity'
          example: []
        goals:
          type: array
          items:
            $ref: '#/components/schemas/JourneyGoal'
          example: []
        exits:
          type: array
          items:
            $ref: '#/components/schemas/JourneyExit'
          example: []
      required:
      - name
      - workflowApiVersion
    JourneyTrigger:
      type: object
      description: Entry trigger configuration for a journey. Defines how contacts enter the journey, such as via API event, scheduled automation, or audience.
      properties:
        key:
          type: string
          description: Unique key for the trigger within the journey
          example: example_value
        name:
          type: string
          description: Display name of the trigger
          example: Example Title
        type:
          type: string
          description: Type of trigger
          enum:
          - APIEvent
          - ScheduledAutomation
          - Event
          - ContactAudience
          example: APIEvent
        eventDefinitionKey:
          type: string
          description: Key of the event definition associated with this trigger, used for API events
          example: example_value
        configurationArguments:
          type: object
          description: Trigger-specific configuration
          example: example_value
    JourneyCollection:
      type: object
      description: Paginated collection of journeys
      properties:
        count:
          type: integer
          description: Total number of journeys matching the query
          example: 10
        page:
          type: integer
          description: Current page number
          example: 10
        pageSize:
          type: integer
          description: Number of items per page
          example: 10
        items:
          type: array
          items:
            $ref: '#/components/schemas/Journey'
          example: []
    EntryEventResponse:
      type: object
      description: Response returned after firing a journey entry event
      properties:
        requestId:
          type: string
          description: Unique identifier for the event request
          example: '500123'
        eventInstanceId:
          type: string
          format: uuid
          description: Unique instance identifier for this event firing
          example: '500123'
    EntryEvent:
      type: object
      description: Event payload used to inject a contact into a journey via the API event trigger.
      properties:
        ContactKey:
          type: string
          description: Unique identifier for the contact entering the journey
          example: example_value
        EventDefinitionKey:
          type: string
          description: Key of the event definition matching the journey entry trigger
          example: example_value
        Data:
          type: object
          description: Additional data to pass to the journey as key-value pairs. These values are available to activities within the journey.
          additionalProperties: true
          example: example_value
      required:
      - ContactKey
      - EventDefinitionKey
    PublishResponse:
      type: object
      description: Response returned when a journey publish operation is initiated
      properties:
        statusId:
          type: string
          description: Identifier for tracking the publish operation status
          example: '500123'
        message:
          type: string
          example: example_value
    JourneyActivity:
      type: object
      description: An activity within a journey. Activities represent the actions performed on contacts, such as sending emails, waiting, or making decisions.
      properties:
        key:
          type: string
          description: Unique key for the activity within the journey
          example: example_value
        name:
          type: string
          description: Display name of the activity
          example: Example Title
        type:
          type: string
          description: Type of activity
          enum:
          - EMAILV2
          - SMSSYNC
          - PUSHNOTIFICATION
          - WAIT
          - RANDOM_SPLIT
          - ENGAGEMENT_SPLIT
          - DECISION_SPLIT
          - JOIN
          - DATAEXTENSIONUPDATE
          - REST
          - CUSTOM
          example: EMAILV2
        configurationArguments:
          type: object
          description: Activity-specific configuration
          example: example_value
        outcomes:
          type: array
          description: Possible outcomes of the activity leading to next steps
          items:
            type: object
            properties:
              key:
                type: string
              next:
                type: string
                description: Key of the next activity in the journey
          example: []
      required:
      - key
      - type
  securitySchemes:
    OAuth2:
      type: oauth2
      description: Marketing Cloud uses OAuth 2.0 client credentials flow for authentication. Obtain a client ID and secret from an installed package in Marketing Cloud Setup, then exchange them for an access token at the authentication endpoint.
      flows:
        clientCredentials:
          tokenUrl: https://YOUR_SUBDOMAIN.auth.marketingcloudapis.com/v2/token
          scopes: {}