Marketing Cloud REST API

openapi: 3.1.0
info:
  title: Salesforce Marketing Cloud REST 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: [email protected]
  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: Assets
  description: >-
    Manage marketing assets including images, documents, content blocks, and
    templates. The Asset API provides CRUD operations for all content types
    stored in Content Builder.
  externalDocs:
    description: Asset API Documentation
    url: https://developer.salesforce.com/docs/marketing/marketing-cloud/guide/asset-api.html
- name: Contacts
  description: >-
    Create, retrieve, update, and delete contacts in Marketing Cloud. Contacts
    represent individuals who interact with your marketing campaigns across
    channels.
  externalDocs:
    description: Contacts API Documentation
    url: https://developer.salesforce.com/docs/marketing/marketing-cloud/references/mc_rest_contacts/createContacts.html
- 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:
  /contacts/v1/contacts:
    post:
      operationId: createContacts
      summary: Salesforce Marketing Cloud Create Contacts
      description: >-
        Creates one or more contacts in Marketing Cloud. Each contact requires a
        contactKey as a unique identifier. You can include attribute values for
        any defined attribute sets such as Email Addresses, MobileConnect
        Demographics, or custom attribute sets.
      tags:
      - Contacts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateContactsRequest'
            example:
              contactKey: example-contact-001
              attributeSets:
              - name: Email Addresses
                items:
                - values:
                  - name: Email Address
                    value: [email protected]
                  - name: HTML Enabled
                    value: true
      responses:
        '200':
          description: Contacts created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactResponse'
        '400':
          description: Bad request - invalid contact data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid or expired access token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many requests - rate limit exceeded
          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
  /contacts/v1/contacts/actions/search:
    post:
      operationId: searchContacts
      summary: Salesforce Marketing Cloud Search Contacts
      description: >-
        Searches for contacts using filter criteria. Supports filtering by
        contactKey, email address, or other contact attributes. Returns matching
        contacts with their associated attribute values.
      tags:
      - Contacts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactSearchRequest'
            example:
              conditionSet:
                operator: AND
                conditionSets: []
                conditions:
                - attribute:
                    groupName: Email Addresses
                    name: Email Address
                  operator: Equals
                  value:
                    items:
                    - [email protected]
              returnAttributes:
              - groupName: Email Addresses
                name: Email Address
              - groupName: Email Addresses
                name: HTML Enabled
      responses:
        '200':
          description: Search results returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactSearchResponse'
        '400':
          description: Bad request - invalid search criteria
          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
  /contacts/v1/contacts/{contactKey}:
    get:
      operationId: getContact
      summary: Salesforce Marketing Cloud Retrieve a Contact by Contact Key
      description: >-
        Retrieves a single contact using the unique contactKey identifier.
        Returns the contact record with all associated attribute sets and values.
      tags:
      - Contacts
      parameters:
      - name: contactKey
        in: path
        required: true
        description: Unique identifier for the contact
        schema:
          type: string
      responses:
        '200':
          description: Contact retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Contact 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
    patch:
      operationId: updateContact
      summary: Salesforce Marketing Cloud Update a Contact
      description: >-
        Updates an existing contact's attributes. Provide only the attribute
        sets and values that need to be changed. Unspecified attributes remain
        unchanged.
      tags:
      - Contacts
      parameters:
      - name: contactKey
        in: path
        required: true
        description: Unique identifier for the contact
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateContactRequest'
      responses:
        '200':
          description: Contact updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Contact 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
    delete:
      operationId: deleteContact
      summary: Salesforce Marketing Cloud Delete a Contact
      description: >-
        Initiates an asynchronous delete operation for a contact identified by
        contactKey. This operation removes the contact and associated data from
        Marketing Cloud. The delete process runs asynchronously and may take
        time to complete.
      tags:
      - Contacts
      parameters:
      - name: contactKey
        in: path
        required: true
        description: Unique identifier for the contact to delete
        schema:
          type: string
      responses:
        '200':
          description: Contact delete operation initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteContactResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Contact 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
  /contacts/v1/attributeSets:
    get:
      operationId: listAttributeSets
      summary: Salesforce Marketing Cloud List Attribute Sets
      description: >-
        Retrieves all attribute sets defined in Marketing Cloud. Attribute sets
        define the structure of contact data, including system attribute sets
        like Email Addresses and MobileConnect Demographics, as well as custom
        attribute sets.
      tags:
      - Contacts
      responses:
        '200':
          description: Attribute sets retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttributeSetsResponse'
        '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:
    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: [email protected]
      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
  /asset/v1/content/assets:
    get:
      operationId: listAssets
      summary: Salesforce Marketing Cloud List Assets
      description: >-
        Retrieves a collection of assets from Content Builder. Supports
        filtering, sorting, and pagination. Assets include emails, templates,
        images, content blocks, and other content types.
      tags:
      - Assets
      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 assets 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: $filter
        in: query
        description: >-
          OData-style filter expression (e.g.,
          assetType.name eq 'htmlemail')
        schema:
          type: string
      responses:
        '200':
          description: Assets retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetCollection'
        '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: createAsset
      summary: Salesforce Marketing Cloud Create an Asset
      description: >-
        Creates a new asset in Content Builder. The asset type determines the
        required and optional fields. Common asset types include htmlemail,
        templatebasedemail, htmlblock, codesnippetblock, and image.
      tags:
      - Assets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssetDefinition'
            example:
              name: Welcome Email
              description: Welcome email sent to new subscribers
              assetType:
                name: htmlemail
                id: 208
              views:
                html:
                  content: '<html><body><h1>Welcome!</h1></body></html>'
                subjectLine:
                  content: Welcome to our newsletter
              data:
                email:
                  options:
                    characterEncoding: utf-8
      respon

# --- truncated at 32 KB (68 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/salesforce-marketing-cloud/refs/heads/main/openapi/salesforce-marketing-cloud-openapi.yml