mcp-server-sfmc 0.5.0 → 1.0.0

package/README.md

@@ -1,6 +1,6 @@
 # mcp-server-sfmc
 
-MCP server providing Salesforce Marketing Cloud language intelligence — AMPscript, SSJS, and GTL — as Model Context Protocol tools, resources, and prompts for AI-assisted development and code review. It also ships a **searchable index** of mirrored Salesforce Help for **Marketing Cloud Engagement** administration and setup (business units, Journey Builder, Automation Studio, tenants, and similar topics), with explicit scoping vs **Marketing Cloud Next** (a separate product).
+MCP server providing Salesforce Marketing Cloud language intelligence — AMPscript, SSJS, and GTL — as Model Context Protocol tools, resources, and prompts for AI-assisted development and code review. Ships two searchable doc indexes: **MCE help** (Salesforce Help for Marketing Cloud Engagement administration and setup) and **MCN developer docs** (Marketing Cloud Next REST API and developer reference). Includes full **Marketing Cloud Next (MCN) platform awareness**: auto-detects whether a project targets MCE or MCN, restricts completions and validation to MCN-supported functions, flags SSJS as unsupported in MCN, surfaces MCN behavioral differences in hover and diagnostics, and provides a **migration toolkit** to analyze and rewrite code for MCN.
 
 Built on [sfmc-language-lsp](https://github.com/JoernBerkefeld/sfmc-language-lsp), the same engine that powers the [SFMC Language Service VS Code extension](https://marketplace.visualstudio.com/items?itemName=joernberkefeld.sfmc-language).
 
@@ -28,7 +28,7 @@ You **do not** have to install the VS Code extension. Pick one way to run the se
 |---|---|
 | **`npx` (no install)** | Default in the examples below. Runs the latest published version from npm on demand; first run may download the package. **Requires Node.js and npm** (which provides `npx`). |
 | **`npm install -g mcp-server-sfmc`** | Same CLI as `npx`, but the package stays on disk so **startup is faster** and you can set `"command": "mcp-server-sfmc"` with empty `args` in your MCP config. |
-| **`npm install mcp-server-sfmc` in a project** | Keeps a **pinned version** in that folder’s `node_modules` — point your MCP config at `npx mcp-server-sfmc` with `cwd` set to the project, or run `./node_modules/.bin/mcp-server-sfmc` directly. |
+| **`npm install mcp-server-sfmc` in a project** | Keeps a **pinned version** in that folder's `node_modules` — point your MCP config at `npx mcp-server-sfmc` with `cwd` set to the project, or run `./node_modules/.bin/mcp-server-sfmc` directly. |
 | **`sfmc-review-diff` (bundled CLI)** | For **CI**: spawns this MCP server, calls `review_change` on a unified diff (stdin or file), exits non-zero on `ERROR` by default. Install the package in the job, then e.g. `git diff base...HEAD \| npx sfmc-review-diff`. |
 
 None of these replace the VS Code extension for **editing** (syntax, LSP, snippets); they only expose the **MCP server** to tools that speak the Model Context Protocol.
@@ -41,20 +41,24 @@ Ready-to-copy workflows (GitHub Actions, GitLab CI, Jenkins, Azure Pipelines, Bi
 
 | Feature | Details |
 |---|---|
-| **Validation** | Syntax errors, unknown functions, arity mismatches, unsupported SSJS syntax |
-| **Lookup** | Full function signatures, parameters, return types, and examples from the SFMC catalog |
+| **Validation** | Syntax errors, unknown functions, arity mismatches, unsupported SSJS syntax; `target: 'next'` flags MCN-incompatible functions and all SSJS |
+| **Lookup** | Full function signatures, parameters, return types, MCN compatibility badge (API version), behavioral notes, and examples |
 | **PR review** | Diff-aware review tool that surfaces issues in the exact lines that changed |
-| **Fix suggestions** | Concrete, compilable replacement code for each detected issue |
-| **Completions** | AMPscript function/keyword completions, SSJS Platform API catalog |
-| **Prompts** | Guided prompts for writing AMPscript, SSJS, reviewing code, and converting between the two |
+| **Fix suggestions** | Concrete, compilable replacement code; `target: 'next'` includes MCN platform issues |
+| **Completions** | AMPscript completions (filtered to MCN-supported when `target: 'next'`); SSJS catalog (redirects to AMPscript for MCN) |
+| **Platform detection** | `detect_sfmc_platform` checks `.mcdevrc.json` (MCE) or `sfdx-project.json` (MCN) in the project root |
+| **MCN compatibility analysis** | `check_mcn_compatibility` analyzes files for MCN readiness — per-function classification (supported / needs review / not supported), SSJS block migration difficulty, and an executive summary |
+| **MCN migration** | `rewrite_for_mcn` (tool + prompt) deterministically rewrites AMPscript and converts convertible SSJS to AMPscript for MCN, then applies AI reasoning to remaining manual-rewrite sections |
+| **Code conversion** | `convertSsjsToAmpscript` and `convertAmpscriptToSsjs` (tool + prompt hybrid) — rule-based conversion with AI-enhanced handling of flagged sections |
+| **Prompts** | Guided prompts for writing AMPscript/SSJS (with MCN constraints), reviewing code, converting between the two, and rewriting for MCN |
 | **Resources** | Full function catalogs, keyword list, unsupported ES6+ syntax list |
-| **MCE help search** | Bundled excerpts from mirrored Salesforce Help (MCE vs Next scoped) |
+| **Help search** | `search_help` (unified, auto-detects MCE vs MCN from project root); `search_mce_help` (MCE help, 7 product scopes); `search_mcn_help` (MCN developer API reference) |
 
 ## Connecting AI clients
 
 ### VS Code (1.99+) + GitHub Copilot — manual `mcp.json`
 
-If you are **not** using the SFMC Language Service extension’s built-in MCP registration, add a `.vscode/mcp.json` file to your project (or copy it from this repo):
+If you are **not** using the SFMC Language Service extension's built-in MCP registration, add a `.vscode/mcp.json` file to your project (or copy it from this repo):
 
 ```json
 {
@@ -136,17 +140,25 @@ Then replace `"command": "npx", "args": ["-y", "mcp-server-sfmc@latest"]` with:
 
 | Tool | Description |
 |---|---|
-| `validate_ampscript` | Validate AMPscript code — unknown functions, arity, delimiter balance, comment syntax |
-| `validate_ssjs` | Validate SSJS — ES6+ usage, missing Platform.Load, wrong API calls |
-| `validate_sfmc_html` | Validate HTML with embedded AMPscript, SSJS, and GTL blocks |
-| `lookup_ampscript_function` | Full signature, parameters, and example for any AMPscript function |
+| `validate_ampscript` | Validate AMPscript code — unknown functions, arity, delimiter balance, comment syntax. `target: 'next'` flags MCN-incompatible functions. |
+| `validate_ssjs` | Validate SSJS — ES6+ usage, missing Platform.Load, wrong API calls. `target: 'next'` flags all SSJS as unsupported. |
+| `validate_sfmc_html` | Validate HTML with embedded AMPscript, SSJS, and GTL blocks. `target: 'next'` enables MCN validation. |
+| `lookup_ampscript_function` | Full signature, parameters, return type, MCN compatibility badge (API version), behavioral notes for MCN, and examples |
 | `lookup_ssjs_function` | Full signature and description for any SSJS Platform function or method |
+| `list_ampscript_functions` | List all AMPscript functions, optionally filtered by `platform: 'next'` to return only MCN-supported functions |
 | `review_change` | Review a unified diff — validates only added lines, maps back to diff line numbers |
-| `suggest_fix` | Generate fix suggestions for each diagnostic in a code snippet |
-| `get_ampscript_completions` | List valid completions at a given cursor position in AMPscript |
-| `get_ssjs_completions` | List SSJS Platform API completions, optionally filtered by prefix |
+| `suggest_fix` | Generate fix suggestions for each diagnostic in a code snippet. `target: 'next'` includes MCN fixes. |
+| `get_ampscript_completions` | List valid completions at a given cursor position; MCN-unsupported functions marked `[MCE only]` when `target: 'next'` |
+| `get_ssjs_completions` | List SSJS Platform API completions, optionally filtered by prefix; redirects to AMPscript completions when `target: 'next'` |
 | `format_sfmc_code` | Apply basic formatting conventions (keyword casing, quote normalisation) |
-| `search_mce_help` | Search bundled Marketing Cloud setup/ops help; use `product_focus` to target **Engagement** vs **Next** |
+| `detect_sfmc_platform` | Detect the target platform for a project — checks `.mcdevrc.json` (→ `"engagement"`) or `sfdx-project.json` (→ `"next"`) |
+| `check_mcn_compatibility` | Analyze one or more AMPscript/HTML files for MCN readiness. Returns per-function classification, SSJS block migration difficulty, and an executive summary with overall migration effort. Run this before `rewrite_for_mcn`. |
+| `rewrite_for_mcn` | Deterministic MCN rewrite engine: fixes `.NET → Java` format strings, removes `StringToDate` wrappers, converts convertible SSJS to AMPscript, marks unsupported functions, annotates the rest as `MANUAL_REWRITE_REQUIRED`. **Prefer the `rewrite_for_mcn` prompt** for interactive use — it calls this tool first, then applies AI reasoning to the flagged sections. Use the tool directly only for structured JSON output in pipelines. |
+| `convertSsjsToAmpscript` | Rule-based SSJS → AMPscript conversion engine: `Platform.Function.*` → AMPscript equivalents, variable/request access, control flow. Flags JS-native constructs as `MANUAL_REWRITE_REQUIRED`. **Prefer the `convertSsjsToAmpscript` prompt** for interactive use. |
+| `convertAmpscriptToSsjs` | Rule-based AMPscript → SSJS conversion engine: variables, control flow, function calls. Flags AMPscript-only constructs as `MANUAL_REWRITE_REQUIRED`. **Prefer the `convertAmpscriptToSsjs` prompt** for interactive use. |
+| `search_help` | **Unified help search** — auto-detects the platform from `projectRoot` and routes to the right doc index. MCN projects search both the developer API reference and MCN admin docs. Pass `target` to override detection. |
+| `search_mce_help` | Search bundled Marketing Cloud Engagement setup/ops help; use `product_focus` to target Engagement vs Next |
+| `search_mcn_help` | Search bundled Marketing Cloud Next developer API documentation (objects, flows, segments, REST/SOAP APIs, AMPscript behavior in MCN) |
 
 ## Resources
 
@@ -157,7 +169,8 @@ Then replace `"command": "npx", "args": ["-y", "mcp-server-sfmc@latest"]` with:
 | `sfmc://ampscript/keywords` | All AMPscript keywords |
 | `sfmc://ssjs/unsupported-syntax` | ES6+ features not supported in SFMC SSJS |
 | `sfmc://mce/product-context` | How **Marketing Cloud Engagement** differs from **Marketing Cloud Next** (when to use which) |
-| `sfmc://mce/help-index` | List of bundled help files and section counts per product scope |
+| `sfmc://mce/help-index` | List of bundled MCE help files and section counts per product scope |
+| `sfmc://mcn/help-index` | List of bundled MCN developer API doc files and chunk counts |
 
 ## Prompts
 
@@ -165,27 +178,90 @@ Access via `/mcp.sfmc.writeAmpscript` etc. in VS Code, or via the prompts API:
 
 | Prompt | Description |
 |---|---|
-| `writeAmpscript` | Generate AMPscript code for a described task |
-| `writeSsjs` | Generate SSJS code for a described task |
-| `reviewSfmcCode` | Review AMPscript or SSJS code for bugs and best-practice violations |
-| `convertAmpscriptToSsjs` | Convert AMPscript code to equivalent SSJS |
+| `writeAmpscript` | Generate AMPscript code for a described task. `target: 'next'` enforces MCN constraints (MCN-supported functions only, Java `SimpleDateFormat` patterns, no SSJS). |
+| `writeSsjs` | Generate SSJS code for a described task. `target: 'next'` redirects to AMPscript instead (SSJS is not available in MCN). |
+| `reviewSfmcCode` | Review AMPscript or SSJS code for bugs and best-practice violations. `target: 'next'` adds MCN compatibility checklist. |
+| `rewrite_for_mcn` | **Primary interface for MCN migration.** Internally calls the `rewrite_for_mcn` tool for all deterministic rewrites, then applies AI reasoning to every `MANUAL_REWRITE_REQUIRED` section — producing a single fully migrated code block with a prose changelog. You always get both the rule-based pass and the AI pass in one step. |
+| `convertSsjsToAmpscript` | **Primary interface for SSJS → AMPscript conversion.** Internally calls the `convertSsjsToAmpscript` tool for rule-based conversion, then AI-reasons over any sections the rules could not handle. |
+| `convertAmpscriptToSsjs` | **Primary interface for AMPscript → SSJS conversion.** Internally calls the `convertAmpscriptToSsjs` tool for rule-based conversion, then applies AI reasoning to flagged AMPscript-only constructs. |
 | `answerMceHowTo` | Guided prompt for admin/setup questions — searches bundled help and keeps Engagement vs Next explicit |
 
+## Migrating code to Marketing Cloud Next
+
+Marketing Cloud Next (MCN) supports **41 of the 150 AMPscript functions** and **does not support SSJS**. Three supported functions have behavioral differences (see below). The migration toolkit guides you from analysis through to a fully rewritten result.
+
+### Recommended workflow
+
+```
+1. detect_sfmc_platform  →  confirm the project targets MCN
+2. check_mcn_compatibility  →  understand scope: which files need work, how hard
+3. rewrite_for_mcn prompt  →  calls the rewrite_for_mcn tool internally, then applies AI
+                               reasoning to any MANUAL_REWRITE_REQUIRED sections
+4. validate_ampscript with target:'next'  →  verify the rewritten code is clean
+```
+
+### What `check_mcn_compatibility` tells you
+
+Pass one or more `{ filename, content }` pairs and get back:
+
+- **Per-function classification** for every AMPscript call site:
+  - ✅ Supported — works as-is
+  - ⚠️ Needs review — supported but has behavioral differences in MCN
+  - ❌ Not supported — no MCN equivalent
+- **SSJS block analysis** — classified as "needs conversion" (has AMPscript equivalents) or "not migratable" (uses JS-native constructs such as `try/catch`, `forEach`, regex)
+- **Migration difficulty per file** — Ready / Minor changes needed / Significant rewrite / Not migratable
+- **Executive summary** across all files
+
+### What `rewrite_for_mcn` does
+
+**Use the `rewrite_for_mcn` prompt** — it is the primary interface and gives you the full result in one step. It first calls the `rewrite_for_mcn` tool internally for all deterministic rewrites, then applies AI reasoning to every section the tool could not handle mechanically. You get both the accuracy of rule-based conversion and the intelligence of an AI pass, without having to invoke them separately.
+
+**Deterministic rewrites (handled by the tool internally):**
+
+- Removes `StringToDate()` wrappers from `FormatDate()` calls (`FormatDate(StringToDate(@x), fmt)` → `FormatDate(@x, fmt)`)
+- Converts `.NET → Java SimpleDateFormat` format strings (e.g. `tt` → `a`)
+- Annotates `Lookup()` calls with an odd number of search arguments
+- Marks MCE-only AMPscript functions with `%%-- NOT SUPPORTED IN MCN %%`
+- Converts convertible SSJS blocks to AMPscript (`Platform.Function.*` → AMPscript equivalents, `Platform.Variable.GetValue/SetValue` → `@variable` references)
+- Flags JS-native SSJS constructs (`try/catch`, array methods, regex, complex logic) as `MANUAL_REWRITE_REQUIRED`
+
+**AI reasoning layer (added by the prompt):** for each `MANUAL_REWRITE_REQUIRED` section, the prompt instructs the AI to attempt a full conversion using its knowledge of AMPscript and SSJS, then produces a single final rewritten code block with a prose changelog covering every change.
+
+> **Pipelines and programmatic use:** call the `rewrite_for_mcn` **tool** directly when you need the structured JSON output (`{ rewrittenCode, changes[], nonMigratableItems[], difficulty, summary }`) without the AI layer — for example in a CI step that feeds results to another tool.
+
+The same hybrid pattern applies to `convertSsjsToAmpscript` and `convertAmpscriptToSsjs`: always use the **prompt** for interactive use; use the **tool** when you need structured output in a pipeline.
+
+### MCN behavioral differences to watch for
+
+| Function | Difference |
+|---|---|
+| `FormatDate` | Uses **Java `SimpleDateFormat`** patterns in MCN instead of .NET. Example: `.NET "M/d/yyyy h:mm:ss tt"` → Java `"M/d/yyyy h:mm:ss a"` |
+| `Lookup` | Search arguments must come in column/value pairs — an **odd argument count causes an error** in MCN. All filter keys must fully specify the composite primary key. |
+| `StringToDate` | Returns a **locale-formatted string** in MCN (G standard format, e.g. `"5/15/2026 1:23:45 PM"`) instead of a dateTime object. Cannot be reliably passed to `FormatDate()` in MCN — use `FormatDate()` directly with the original date string instead. |
+
+### CloudPages functions — not migratable
+
+Functions that depend on CloudPages context (`CloudPagesURL`, `RequestParameter`, `QueryParameter`, `Redirect`, `MicrositeURL`) have no equivalent in Marketing Cloud Next. `check_mcn_compatibility` and `rewrite_for_mcn` flag these as **Not migratable** immediately.
+
 ## Writing effective prompts
 
 ### Automatic tool use
 
-Clients that honour the MCP `instructions` field (Cursor, Claude Desktop, GitHub Copilot Agent mode) will call `search_mce_help` automatically whenever you ask an MCE administration or setup question — no special phrasing needed. If your client does not process server instructions, or if you want explicit control, the templates below help.
+Clients that honour the MCP `instructions` field (Cursor, Claude Desktop, GitHub Copilot Agent mode) will call `search_help` or `search_mce_help` automatically whenever you ask an MCE administration or setup question — no special phrasing needed. If your client does not process server instructions, or if you want explicit control, the templates below help.
 
 ### Quick reference: which tool or prompt to use
 
 | Situation | What to do |
 |---|---|
-| MCE admin question (classic Engagement) | Ask naturally; the server will call `search_mce_help` for you. Or use the `answerMceHowTo` prompt with `assumeProduct: engagement`. |
-| Marketing Cloud Next question | Use `answerMceHowTo` with `assumeProduct: next`, or add "for Marketing Cloud Next" to your question. |
-| Not sure which product | Use `answerMceHowTo` with `assumeProduct: unsure`, or add "check both Engagement and Next" to your question. |
-| Write or validate AMPscript | Use the `writeAmpscript` prompt, or ask directly (the server auto-validates). |
-| Write or validate SSJS | Use the `writeSsjs` prompt, or ask directly. |
+| MCE admin question (classic Engagement) | Ask naturally; the server calls `search_help` (or `search_mce_help` directly). Or use the `answerMceHowTo` prompt with `assumeProduct: engagement`. |
+| Marketing Cloud Next developer API question | The server calls `search_help` or `search_mcn_help` automatically. Or use `search_mcn_help` explicitly. |
+| MCN operational / migration / setup question | Use `search_mce_help` with `product_focus: 'next'`, or ask naturally and the server routes it. |
+| Not sure which product | Use `answerMceHowTo` with `assumeProduct: unsure`, or `search_help` without a `target`. |
+| Write or validate AMPscript | Use the `writeAmpscript` prompt, or ask directly (the server auto-validates). Add `target: 'next'` for MCN. |
+| Write or validate SSJS | Use the `writeSsjs` prompt, or ask directly. Note: SSJS is not supported in MCN. |
+| Check if code is MCN-ready | Use `check_mcn_compatibility` with your file contents. |
+| Migrate code to Marketing Cloud Next | Use the `rewrite_for_mcn` **prompt** — it calls the tool internally for deterministic rewrites, then applies AI reasoning to any remaining manual sections. Use the tool directly only when you need structured JSON output in a pipeline. |
+| Convert SSJS ↔ AMPscript | Use the `convertSsjsToAmpscript` or `convertAmpscriptToSsjs` **prompt** — same hybrid pattern: tool runs first, AI handles what the rules couldn't. |
 | Review a code diff | Use the `reviewSfmcCode` prompt or mention "review the following diff". |
 
 ### Copy-paste prompt templates
@@ -199,15 +275,33 @@ Search the Marketing Cloud Engagement help (product_focus: engagement) and tell
 Cite which product version your steps apply to and note if the bundled docs are incomplete.
 ```
 
-#### Marketing Cloud Next
+#### Marketing Cloud Next — developer API
 
 ```
-Search the Marketing Cloud Next help (product_focus: next) and tell me:
+Search the Marketing Cloud Next developer docs and tell me:
 <your question here>
 
 Confirm the steps apply to Marketing Cloud Next, not classic Engagement.
 ```
 
+#### MCN migration analysis
+
+```
+Check these files for Marketing Cloud Next compatibility and give me an executive summary:
+<paste file contents>
+```
+
+#### Rewrite code for MCN
+
+Use the `rewrite_for_mcn` **prompt** — it first runs the deterministic rewrite tool, then applies AI reasoning to any sections that need it. You get the full result in one step.
+
+```
+Rewrite the following AMPscript/HTML for Marketing Cloud Next:
+<paste code>
+
+Apply all deterministic fixes, convert convertible SSJS to AMPscript, and explain every change.
+```
+
 #### Unknown product / migration question
 
 ```
@@ -241,7 +335,9 @@ In clients that support MCP prompts (e.g. VS Code with the `/mcp.sfmc.answerMceH
 - If the bundled excerpts do not cover the question fully, the AI says so and suggests verifying in the live Salesforce Help.
 - Function signatures (AMPscript / SSJS) are always sourced from the language catalog, not from training data.
 
-## Refresh bundled Marketing Cloud Engagement help
+## Refresh bundled help indexes
+
+### Marketing Cloud Engagement help
 
 The published npm package includes `bundled/mce-help/chunks.json`, produced by `npm run bundle-mce-help`. By default the bundler uses the path in **`MCE_HELP_DOCS`** (see `scripts/bundle-mce-help.mjs`); set it to the root of your mirrored MCE Help Markdown tree when not using the maintainer default.
 
@@ -254,6 +350,19 @@ npm test
 
 Example: `MCE_HELP_DOCS=/absolute/path/to/mce-help-mirror npm run bundle-mce-help`
 
+### Marketing Cloud Next developer docs
+
+The published npm package includes `bundled/mcn-help/chunks.json`, produced by `npm run bundle-mcn-help`. Set **`MCN_HELP_DOCS`** to the root of your mirrored MCN developer docs tree when not using the maintainer default (see `scripts/bundle-mcn-help.mjs`).
+
+```bash
+cd mcp-server-sfmc
+npm run bundle-mcn-help
+npm run build
+npm test
+```
+
+To rebuild both indexes in one command: `npm run bundle-all`
+
 ## AI code review in pull requests
 
 ### GitHub Copilot (cloud agent)

package/bundled/mcn-help/chunks.json

@@ -0,0 +1 @@
+{"generatedAt":"2026-06-06T05:15:52.623Z","sourceDir":"docs/developer.salesforce/marketing/marketing-cloud-growth","chunkCount":48,"chunks":[{"id":"mc-administration.md#0","file":"mc-administration.md","relativePath":"mc-administration.md","heading":"Configure Your Marketing Cloud Next Org","body":"To get started, install and deploy data and configure your users.\n\nTo use Marketing Cloud, first deploy data kits in Data Cloud. An administrator can deploy these data kits in the Salesforce web app. See _Salesforce Help_: [Configure Your Marketing Data](https://help.salesforce.com/s/articleView?id=mktg.mktg_admin_data_kits_ref.htm).\n\nCreate accounts for each marketing user, and apply the permissions they require to do their job. We recommend that you use one of these permission sets.\n\nMarketing Cloud Admin\nThis permission set provides access to most tasks in Salesforce Setup and full control on campaigns, segments, and flows.\n\nMarketing Cloud Manager\nThis permission set gives full control to manage campaigns, segments, and campaign (non-admin) flows.\n\nFor more information, see [Assign Permission Sets for Marketing Cloud](https://help.salesforce.com/s/articleView?id=mktg.mktg_admin_setup_perms_assign.htm).\n\nTo complete setup, your org needs a Data Cloud Architect to install data kits, deploy data streams, and configure identity resolution rules. For more information about creating Data Cloud Architects, see [Data Cloud Standard Permission Sets](https://help.salesforce.com/s/articleView?id=data.c360_a_userpermissions.htm).\n\nAPI users use standard Salesforce accounts. Access to Salesforce APIs is managed using Connected Apps. See [Manage Access to a Connected App](https://help.salesforce.com/s/articleView?id=xcloud.connected_app_manage.htm).\n\n*   [View and Manage Users](https://help.salesforce.com/s/articleView?id=platform.admin_users.htm)"},{"id":"mc-connect-apis-data-cloud-jwt-encode.md#0","file":"mc-connect-apis-data-cloud-jwt-encode.md","relativePath":"mc-connect-apis-data-cloud-jwt-encode.md","heading":"mc-connect-apis-data-cloud-jwt-encode","body":"# Python Code Example for Encoding a JWT\n\nThis Python code example encodes a JWT based on your client ID, username, and private key. It then issues a request to the `/services/oauth2/token` endpoint, passing the JWT in the body of the request. The resulting output contains the bearer token, which you use to authenticate subsequent requests to the API.\n\nTo run this example, install the `requests` library and the PyJWT library with added cryptography support. You can install these libraries using `pip`.\n\nNext, create an environment variable called `CLIENTID_DC` that contains your client ID (also referred to as your consumer key), and create another environment variable called `USER_DC` that contains your user ID.\n\nFinally, change the value of the `keyFile` variable in the `main` function to refer to your RSA private key.\n\nIf the request is successful, the response object includes the access token."},{"id":"mc-connect-apis-data-cloud.md#0","file":"mc-connect-apis-data-cloud.md","relativePath":"mc-connect-apis-data-cloud.md","heading":"Connect to the Data Cloud API","body":"The Data Cloud API is a high-performance API for ingesting data into Data Cloud. You can also use it to query data and to manage calculated data insights for Marketing Cloud. The Data Cloud API has strict authentication requirements compared to other REST-based Salesforce APIs.\n\nUse Connect API to manage segments and identity resolution rulesets in Data Cloud. For information about connecting to Connect API, see [Connect to REST-based APIs](./mc-connect-apis-rest.md).\n\nInteracting with the Data Cloud API requires a signed digital certificate. You can use a private key and certificate issued by a certification authority. Alternatively, you can use OpenSSL to create a key and a self-signed digital certificate. Here's how to create a self-signed certificate with OpenSSL.\n\n1.   At the command line, create a directory to store your certificate and private key.\n\n2.   Create a 2048-bit RSA key.\n\n3.   Use the private key to sign a certificate. Enter details about the certificate, or press Enter at each prompt to accept the default value.\n\nA connected app is a framework that enables an external application to integrate with Salesforce using APIs. Create connected apps in the Salesforce web app.\n\n1.   In Setup, in the Quick Find box, enter `apps`, and then select **App Manager**.\n2.   Click **New Connected App**.\n3.   For Connected App Name, enter an app name and your email address.\n4.   Select **Enable OAuth Settings**.\n5.   For **Callback URL**, enter `http://localhost:1717/OauthRedirect`.\n6.   Select **Use digital signatures**, and then click **Browse**.\n7.   Select your self-signed certificate.\n8.   Add the OAuth scopes that are necessary for your use case. For example, if your use case requires you to ingest content, add the `Manage Data Cloud Ingestion API data (cdp_ingest_api)` scope. Also add the `Perform requests at any time (refresh_token, offline_access)` scope so that you can refresh your bearer token as needed. See [OAuth Tokens and Scopes](https://help.salesforce.com/s/articleView?id=xcloud.remoteaccess_oauth_tokens_scopes.htm).\n9.   Click **Save**.\n10.   Click **Manage Consumer Details**.\n11.   Copy the **Consumer Key** value. This value is also referred to as the client ID. You use the client ID value when you encode a Java Web Token (JWT).\n\nEncode a JWT using the steps outlined in [OAuth 2.0 JWT Bearer Flow for Server-to-Server Integration](https://help.salesforce.com/s/articleView?id=xcloud.remoteaccess_oauth_jwt_flow.htm).\n\nWe recommend that you use libraries for your preferred programming language, such as PyJWT for Python, `jwt-encode` for JavaScript, or `java-jwt` for Java. We provide a [code example](./mc-connect-apis-data-cloud-jwt-encode.md) that uses PyJWT to encode the JWT and request a token.\n\nIf you’re using the [Salesforce Data Cloud APIs Postman collection](https://www.postman.com/salesforce-developers/workspace/salesforce-developers/collection/14448118-8145476a-1797-4b2a-b219-37c6d438d956?tab=variables), skip the process of encoding the JWT and requesting a bearer token—the Postman collection handles this step for you. In the Postman collection, on the Variables tab for the parent folder, populate the `loginUrl`, `clientId`, `userName`, and `privateKey` fields with the values that you obtained earlier. Next, send a request to the API. When you send a request, a prerequest script encodes the JWT and uses it to retrieve a bearer token. It also creates variables that track the age of the token and automatically requests a new token if the existing token is expired.\n\nTo request an access token, issue a POST request to the login endpoint for your Salesforce instance.\n\nIf the request is successful, the response object includes the access token, the permission scope, your tenant-specific API URL, an identity URL, and the token type. The value of `token_type` is always `Bearer`.\n\nUse your access token to obtain a token specifically for Data Cloud by issuing a POST request to the `/services/a360/token` endpoint.\n\nIf the request is successful, the response includes an instance URL and an access token.\n\nUse the access token to issue subsequent requests to the Data Cloud API.\n\nWhen you make subsequent calls to the Data Cloud API, include your token as a request header using the bearer token syntax.\n\nTest your authentication token by issuing a GET call to the `/api/v1/metadata/` endpoint.\n\nIf the request is successful, the response includes information about the data model objects in your Data Cloud account.\n\nAuthentication tokens are valid until the time specified in the JWT that you used to obtain the bearer token. To continue using the API after the bearer token expires, request a new one.\n\n*   _JWT.io_: [Libraries for Token Signing/Verification](https://jwt.io/libraries)"},{"id":"mc-connect-apis-info.md#0","file":"mc-connect-apis-info.md","relativePath":"mc-connect-apis-info.md","heading":"Which API Should I Use?","body":"As a Marketing Cloud Next developer, you’re most likely to interact with REST, Bulk, and Data Cloud APIs. However, multiple APIs are available for handling different needs and use cases.\n\nUse REST API to query, create, and modify data in your Salesforce org using JSON requests. You can also use this API to send transactional messages and manage Salesforce users. An advantage of using REST API is that most modern applications and programming languages include features that make it easier to implement REST calls. REST API also supports composite requests, which you can use to send up to 25 requests in a single call. Most REST API requests are handled synchronously, but a few are asynchronous.\n\nBulk API 2.0 is an asynchronous, REST-based API for the Salesforce platform. You can use it to create, manage, and query large volumes of data in your Salesforce org. Any request that includes 2,000 records or more is a good candidate for Bulk API 2.0. Because it’s asynchronous, requests to Bulk API 2.0 require you to issue separate requests to create a job, upload content, check the status of the job, and close the job when it’s complete.\n\nSOAP API performs many of the same functions as REST API. An advantage of using SOAP API is that it supports Web Services Security (WS-Security) headers, which can provide end-to-end security for API requests. SOAP requests are typically larger and more complex than their REST equivalents. As a result, they require more bandwidth, memory, and processing power. Like REST API, most SOAP API requests are synchronous, but a few are asynchronous.\n\nUse Metadata API to read and manage flows. For example, Metadata API is helpful when you want to move flows from a development environment to your production environment.\n\nUse the REST-based Connect API to upload and publish content such as images and emails to your marketing content workspace.\n\nUse the streaming operations in Data Cloud API to create, update, or delete individual records synchronously. For example, you can use the streaming operations to add transaction data to Data Cloud from an external commerce platform as new records are generated.\n\nData Cloud API also includes bulk operations, which you can use to bring large quantities of data into Data Cloud asynchronously. For example, use bulk requests to synchronize Data Cloud with an external database.\n\n*   [REST API Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/intro_what_is_rest_api.htm)\n*   [SOAP API Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.api.meta/api/sforce_api_quickstart_intro.htm)\n*   [Bulk API 2.0 and Bulk API Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.api_asynch.meta/api_asynch/asynch_api_intro.htm)\n*   [Connect API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/intro_what_is_chatter_connect.htm)\n*   [Data Cloud Reference Guide](https://developer.salesforce.com/docs/atlas.en-us.c360a_api.meta/c360a_api/c360a_api_intro_cdpapis.htm)\n*   [Metadata API](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_intro.htm)"},{"id":"mc-connect-apis-rest.md#0","file":"mc-connect-apis-rest.md","relativePath":"mc-connect-apis-rest.md","heading":"Connect to REST-based APIs","body":"To connect to any REST-based API, such as REST API, Bulk API 2.0, or Connect API, follow these steps. For testing, use the Salesforce collection for Postman, which handles authorization for you.\n\nBefore you complete these steps, create a connected app. See [Create a Connected App](https://help.salesforce.com/s/articleView?id=xcloud.connected_app_create.htm).\n\nAlso, activate OAuth2 settings in the connected app. See [Enable OAuth Settings for API Integration](https://help.salesforce.com/s/articleView?id=xcloud.connected_app_create_api_integration.htm).\n\nAfter you activate the OAuth2 settings for the connected app, copy the Consumer Key and Consumer Secret values for the app. The Consumer Key maps to the `client_id` value that you use to obtain the authentication token, and the Consumer Secret maps to the `client_secret`.\n\nIssue a POST request to the `/services/oauth2/token` endpoint. The body of the request must contain the consumer ID and secret for your Connected App. It must also contain the username and password of your API user.\n\nIf your request is accepted, the API returns a 200 response that contains information about the token.\n\nCopy the value of the `access_token` property.\n\nWhen you make subsequent calls to REST API or Bulk API 2.0, provide your authentication token as a header using the Bearer token syntax.\n\nAn easy way to test your authentication token is to issue a GET call to the `/services/data/API_VERSION/limits` endpoint.\n\nIf your request is successful, the response includes information about the API usage limits that apply to your account.\n\nAuthentication tokens expire based on the session policy for your org. When your token expires, issue another POST request to the authentication endpoint to obtain a new token.\n\n*   Trailhead: [Quick Start: Connect Postman to Salesforce](https://trailhead.salesforce.com/content/learn/projects/quick-start-connect-postman-to-salesforce)"},{"id":"mc-connect-apis-soap.md#0","file":"mc-connect-apis-soap.md","relativePath":"mc-connect-apis-soap.md","heading":"Connect to SOAP-Based API","body":"To use SOAP API, pass your username, password, and security token to the `login()` operation. When you do, the API returns information about your API user. It also provides a session ID, which you include in the header of each subsequent SOAP request that you issue. A session ID remains valid for 2 hours. After the session ID expires, call the `login()` operation again to obtain a new one.\n\nThe Salesforce Platform requires you to provide a security token to authorize requests that you make to SOAP API. A security token is a string of text that is unique to your user. Later, when you call the `login()` operation, you append the security token to your password. If you don’t have a security token or you lost it, you can obtain one using the Salesforce web app.\n\n1.   In Salesforce, click your profile icon in the top-right corner of the page, and then click **Settings**.\n2.   Under My Personal Information, click **Reset My Security Token**.\n3.   Click **Reset Security Token**.\n4.   Check the email address that’s associated with your Salesforce account for a message from [info@salesforcedevs.com](mailto:info@salesforcedevs.com). The email contains your new security token. The security token remains valid until you request a new one or until you change your password.\n\nA Web Services Description Language (WSDL) file describes the functionality of a web service such as an API. Salesforce provides two WSDLs: an Enterprise WSDL that reflects the exact configuration of your Salesforce org and a Partner WSDL that applies to all Salesforce orgs. You can download both WSDL files using the Salesforce web app.\n\n1.   From Setup, in the Quick Find box, enter `API`.\n2.   Under Integrations, click **API**.\n3.   Under Enterprise WSDL, click **Generate Enterprise WSDL**.\n4.   Click **Generate**.\n\nIn some web browsers, the contents of the WSDL are displayed in a new browser window. In this situation, right-click anywhere on the page, click **Save page as**, and then save the WSDL file.\n\nThe instructions for loading a WSDL into your web services client depend on which client you use. Consult the documentation for your client. These instructions describe using SoapUI.\n\n1.   On the File menu, click **New SOAP Project**.\n2.   On the New SOAP Project window, enter a name for the project.\n3.   Next to Initial WSDL, click **Browse**.\n4.   Locate the WSDL file that you downloaded earlier. Click **Open**, and then click **OK**.\n\nSoapUI parses the WSDL file and generates a list of all available API operations.\n\nAfter you obtain your security token and set up your SOAP client, you can issue a request to the `login()` operation to obtain your session ID.\n\n1.   In your SOAP client, create a request that uses the `login()` operation.\n\n2.   In the body of the SOAP request, delete the contents of the SOAP header, which is everything between `<soapenv:Header>` and `</soapenv:Header>`.\n\n3.   Change the value of `urn:username` to the username of your API user.\n\n4.   Change the value of `urn:password` to the password of your API user, and then paste your security token to the end of the password.\n\n5.   Submit the SOAP request. If you entered the correct username and password, the response from the API resembles this example.\n\nThe URLs and IDs in this example are randomly generated and can’t be used to issue or authenticate URL requests.\n\n1.   Copy the value between the `<sessionId>...</sessionId>` tags.\n\nIn subsequent requests that you issue to the API, add the session ID to the SOAP header."},{"id":"mc-connect-apis.md#0","file":"mc-connect-apis.md","relativePath":"mc-connect-apis.md","heading":"mc-connect-apis","body":"# Connect to Salesforce APIs to Interact with Marketing Cloud\n\nHow you connect an API depends on which API you plan to use. To use REST-based APIs, including REST API, Bulk API 2.0, and Data Cloud API, create a connected app with the appropriate OAuth settings. See [Connect to REST-based APIs](./mc-connect-apis-rest.md) and [Connect to the Salesforce Data Cloud API](./mc-connect-apis-data-cloud.md).\n\nTo use SOAP API, download a WSDL file and authenticate with a user account. See [Connect to SOAP API](./mc-connect-apis-soap.md)."},{"id":"mc-getting-started.md#0","file":"mc-getting-started.md","relativePath":"mc-getting-started.md","heading":"Get Started with Marketing Cloud Next","body":"This developer guide describes API functionality in Marketing Cloud Next. If you can’t access the features in this guide, contact [Salesforce Customer Support](https://help.salesforce.com/s/articleView?id=000384365&type=1).\n\nMarketing Cloud Next brings the power of the Salesforce platform to your organization’s marketing efforts. Work with Salesforce leads and contacts, create campaigns and flows, and integrate with Data Cloud to load and harmonize data from multiple sources.\n\nThe product formerly called Marketing Cloud is now called Marketing Cloud Engagement. Marketing Cloud Next, Marketing Cloud Engagement, and Marketing Cloud Account Engagement use different APIs that aren’t compatible with each other.\n\nFor more information about developing for Marketing Cloud Engagement, see [Marketing Cloud Engagement APIs and Programmatic Languages](https://developer.salesforce.com/docs/marketing/marketing-cloud/overview).\n\nFor more information about developing for Marketing Cloud Account Engagement, see [Account Engagement API](https://developer.salesforce.com/docs/marketing/pardot/overview).\n\nLearn when, why, and how to use Salesforce APIs.\n\n*   [Which APIs Should I Use?](./mc-connect-apis-info.md)\n*   [View Training Resources](./mc-resources-trailhead.md)\n*   [Watch Developer Videos](./mc-resources-videos.md)\n\nVarious admins are required to configure Marketing Cloud Next, including a Salesforce admin, a Data Cloud Architect, and an optional marketing admin.\n\n*   [Configure your Marketing Cloud Next Org](./mc-administration.md)\n\nTo interact with Marketing Cloud Next using APIs, configure your development environment.\n\n*   [Connect to Salesforce APIs](./mc-connect-apis.md)\n*   [Set Up Salesforce Development Tools](./mc-resources.md)\n\nAfter you connect to an API, you’re ready to start managing your data and assets.\n\n*   [Manage Objects](./mc-manage-objects.md)\n*   [Manage Content](./mc-manage-content.md)\n*   [Explore Reference Content](https://developer.salesforce.com/docs/marketing/marketing-cloud-growth/references)\n*   [Review Security Best Practices](./mc-security.md)"},{"id":"mc-manage-content-create.md#0","file":"mc-manage-content-create.md","relativePath":"mc-manage-content-create.md","heading":"Upload Content to Your Content Workspace for Marketing Cloud","body":"Use the [CMS Contents](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_cms_contents.htm) endpoints in Connect API to upload content to your marketing content workspace.\n\nWhen you upload files to your content workspace, you specify a channel ID to associate them with. If you already know the channel ID that you want to use, skip this step. Otherwise, retrieve a list of channel IDs by issuing a GET request to the `/services/data/{apiVersion}/connect/cms/delivery/channels/` endpoint.\n\nIf the request is successful, the response includes a list of channels in your content workspace.\n\nDetermine which channel that you want to upload the content into, and then copy its `channelId`.\n\nIssue a POST request to the `/services/data/{apiVersion}/connect/cms/contents`. The body of this request must have a content type of `multipart/form-data`. In a multi-part message, the parts are separated from each other using a unique boundary string. The first part of the request body must be a JSON object that contains information about the file that you’re uploading. The second part contains the file.\n\nIf the request is successful, the response includes metadata about the content item.\n\nCopy the value of the `managedContentId` property. You need this ID to publish the content item.\n\nTo make the content available to use in messages, publish it. For more information, see [Publish Content Items](./mc-manage-content-publish.md).\n\n*   [uploadContent](https://developer.salesforce.com/docs/marketing/marketing-cloud-growth/references/mc-connect-content/mc-manage-content-connect-upload.html)\n*   [publishContent](https://developer.salesforce.com/docs/marketing/marketing-cloud-growth/references/mc-connect-content/mc-manage-content-connect-publish.html)"},{"id":"mc-manage-content-form-handlers.md#0","file":"mc-manage-content-form-handlers.md","relativePath":"mc-manage-content-form-handlers.md","heading":"Integrate Form Submissions with the Connect API","body":"Form handlers provide a method for using externally hosted forms to gather information and bring that information into Salesforce.\n\nFor security and scalability, we recommend that you use server-side processes to integrate form handlers directly with the API. In this type of integration, handling a form submission involves these steps:\n\n1.   A user submits the form. The form payload includes a Marketing Cloud-generated `form_id` attribute as a hidden field or URL parameter.\n2.   A server-side process receives the submission, processes it, and calls the Connect API. This process dynamically generates the correct endpoint URL using the `form_id` and constructs the request body based on the fields and values in the form.\n3.   The Form Handler receives the API call and triggers a flow.\n\nWhen a form submission triggers a flow, the flow can use the information in the form to send emails, update records, and perform other actions.\n\nBefore you configure your site to integrate with the Connect API, set up [My Domain](https://help.salesforce.com/s/articleView?id=xcloud.domain_name_overview.htm&type=5) to create a subdomain that’s specific to your organization. When you use the API to handle form submissions, your API calls must use domains that use the format [https://YOUR_SUBDOMAIN.my.salesforce.com](https://your_subdomain.my.salesforce.com/).\n\nUsing other URLs results in a `403 Forbidden` error. When you use a My Domain URL and a valid authentication method (usually an `Authorization: Bearer` header that includes an OAuth token) to make API calls, you’re granted full access to the Connect API.\n\n1.   Create and publish a form handler and a corresponding flow. See _Salesforce Help_: [Connect External Forms to Salesforce Objects by Using Form Handlers](https://help.salesforce.com/s/articleView?id=mktg.mktg_content_connect_external_forms_to_salesforce_objects_with_form_handler.htm).\n2.   Locate the Content Key for the form handler.\n\nThe Content Key is also referred to as the API Name. Find the Content Key on the details page for the form handler in Marketing Cloud Next or by using the Connect API to [retrieve channel contents](https://developer.salesforce.com/docs/marketing/marketing-cloud-growth/references/mc-connect-content/mc-manage-content-connect-get-channel-contents.html).\n\n1.   Create a process hosted on your server that receives data from the form, processes it, and sends it to Salesforce via the Connect API.\n\nThe implementation steps vary depending on your site’s technology stack, your organization’s code and security policies, and the structure and content of the information you capture in your forms.\n\nIf your Form Handler requires reCAPTCHA, your server-side process can’t generate the validation token. Capture the `token` in the client browser during the initial form submission and pass it to your server-side process to include in the API payload.\n\nThe process must send a POST request to your subdomain. The request endpoint includes the Content Key for the form handler, as shown in this example.\n\nThe body of the POST request contains a `formData` object that includes the field names to update. The keys in the `formData` object must exactly match the external field names you configured in the Form Handler settings."},{"id":"mc-manage-content-publish.md#0","file":"mc-manage-content-publish.md","relativePath":"mc-manage-content-publish.md","heading":"Publish Content Items in Marketing Cloud","body":"When you [upload a content item to your content workspace](./mc-manage-content-create.md), you can’t use it in messages until you publish it.\n\nTo publish content, issue a POST request to the `/services/data/{apiVersion}/connect/cms/contents/publish` endpoint. The body of the request must contain an array called `contentIds`. Each item in the array is the content ID (`managedContentId`) of a content item that you want to publish.\n\nIf the request is successful, the response includes a publish date and deployment ID.\n\n*   [uploadContent](https://developer.salesforce.com/docs/marketing/marketing-cloud-growth/references/mc-connect-content/mc-manage-content-connect-upload.html)\n*   [publishContent](https://developer.salesforce.com/docs/marketing/marketing-cloud-growth/references/mc-connect-content/mc-manage-content-connect-publish.html)\n*   [unpublishContent](https://developer.salesforce.com/docs/marketing/marketing-cloud-growth/references/mc-connect-content/mc-manage-content-connect-unpublish.html)"},{"id":"mc-manage-content.md#0","file":"mc-manage-content.md","relativePath":"mc-manage-content.md","heading":"mc-manage-content","body":"# Manage Content in Marketing Cloud\n\n_Content_ refers to assets such as images, emails, and other files that you use to create your messages. To manage content programmatically, use [Connect API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/intro_what_is_chatter_connect.htm).\n\n*   [Upload Content to Your Content Workspace](./mc-manage-content-create.md)"},{"id":"mc-manage-flows-get.md#0","file":"mc-manage-flows-get.md","relativePath":"mc-manage-flows-get.md","heading":"Get a List of Flows","body":"Retrieve a list of flows using the [Flow object](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_visual_workflow.htm) in Metadata API.\n\nThis procedure uses the Salesforce CLI to interact with Metadata API. Before you begin, complete these prerequisite steps.\n\n1.   [Install the Salesforce CLI](https://developer.salesforce.com/tools/salesforcecli).\n2.   [Create a project](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_ws_create_new.htm).\n3.   [Authorize your org](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_auth_web_flow.htm).\n\nBefore you can retrieve data from Metadata API, you must create a manifest file. This file specifies the type of information that you want to interact with.\n\n1.   In your project directory, create a file called `package.xml`.\n2.   Paste this code into the file.\n\nAfter you create the manifest file, you can execute a command to retrieve the flows. The Salesforce CLI connects to your target org and downloads the objects that are specified in the manifest file.\n\n1.   At the command line, run this command to retrieve the flows in your org.\n\nThe CLI connects to Metadata API and begins to retrieve content.\n\n1.   In your project directory, go to the `force-app/main/default/flows` directory. The directory contains an XML file for each flow in your org.\n\nFlows that are associated with campaigns follow the naming format `flow_{campaignId}_{epochTimeMs}.flow-meta.xml`. In this naming format, `{campaignId}` is the unique ID of the campaign ID that the flow is associated with. `{epochTimeMs}` is the date and time when the campaign was created, expressed as a Unix timestamp with milliseconds."},{"id":"mc-manage-flows.md#0","file":"mc-manage-flows.md","relativePath":"mc-manage-flows.md","heading":"mc-manage-flows","body":"# Manage Flows in Marketing Cloud\n\nWhen you create a campaign, Marketing Cloud Next automatically creates a flow and associates it with the campaign. You can use a flow to send a single message, or to send more complex, multi-channel messages."},{"id":"mc-manage-identity-resolution-get-details.md#0","file":"mc-manage-identity-resolution-get-details.md","relativePath":"mc-manage-identity-resolution-get-details.md","heading":"mc-manage-identity-resolution-get-details","body":"# Get Details of an Identity Resolution Ruleset for Marketing Cloud\n\nRetrieve information about a data resolution ruleset using the [Data Cloud Identity Resolution Ruleset](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_cdp_ssot_identity_resolution.htm) endpoint in Connect API.\n\nBefore you send a request to Connect API, obtain a bearer token. For more information, see [Connect to REST-based APIs](./mc-connect-apis-rest.md).\n\nTo retrieve information about an identity resolution ruleset, send a GET request to the `/services/data/{apiVersion}/ssot/identity-resolutions/{identityResolutionId}` endpoint, where `{identityResolutionId}` is the unique ID of the ruleset.\n\nIf the request is successful, the response body contains details of the ruleset."},{"id":"mc-manage-identity-resolution-get.md#0","file":"mc-manage-identity-resolution-get.md","relativePath":"mc-manage-identity-resolution-get.md","heading":"mc-manage-identity-resolution-get","body":"# Get a List of Identity Resolution Rulesets for Marketing Cloud\n\nRetrieve a list of data resolution rulesets using the [Data Cloud Identity Resolution Rulesets](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_cdp_ssot_identity_resolutions.htm) endpoint in Connect API.\n\nBefore you send a request to Connect API, obtain a bearer token. For more information, see [Connect to REST-based APIs](./mc-connect-apis-rest.md).\n\nTo retrieve a list of identity resolution rulesets, send a GET request to the `/services/data/{apiVersion}/ssot/identity-resolutions` endpoint.\n\nIf the request is successful, the response body lists the identity resolution rulesets in your org."},{"id":"mc-manage-identity-resolution-run-now.md#0","file":"mc-manage-identity-resolution-run-now.md","relativePath":"mc-manage-identity-resolution-run-now.md","heading":"Run an Identity Resolution Ruleset for Marketing Cloud","body":"Run an identity resolution ruleset job on demand by using the [Data Cloud Identity Resolution Ruleset Run Now](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_cdp_ssot_identity_resolution_run.htm) endpoint in Connect API.\n\nBefore you send a request to Connect API, obtain a bearer token. For more information, see [Connect to REST-based APIs](./mc-connect-apis-rest.md).\n\nTo run an identity resolution ruleset immediately, send a POST request to the `/ssot/identity-resolutions/{identityResolutionRulesetName}/actions/run-now` endpoint. Replace `{identityResolutionRulesetName}` with the name of the ruleset that you want to run.\n\nIf the request is accepted, the response body describes the result of running the ruleset.\n\nThere are four possible values for `resultCode`.\n\n*   `ExceededMaximumNumberOf​SuccessfulRunsAllowedIn24Hours`\n*   `IdentityResolutionJobIsAlready​Running`\n*   `NoPendingChangesJobRunSkipped`\n*   `SuccessfullySubmittedIdentity​ResolutionJobRunRequest`"},{"id":"mc-manage-identity-resolution.md#0","file":"mc-manage-identity-resolution.md","relativePath":"mc-manage-identity-resolution.md","heading":"mc-manage-identity-resolution","body":"# Manage Identity Resolution in Marketing Cloud\n\nData Cloud identity resolution rules help consolidate your marketing data. By taking data from multiple sources and combining them into a single source of truth, you gain a comprehensive view of your customers. Identity resolution uses matching and reconciliation rules to link data about people or accounts into unified profiles. Each unified profile contains all the unique contact point values from all sources.\n\nTo manage identity resolutions, use the `/ssot/identity-resolutions` endpoint in Connect API."},{"id":"mc-manage-objects-create-bulk.md#0","file":"mc-manage-objects-create-bulk.md","relativePath":"mc-manage-objects-create-bulk.md","heading":"Create Multiple Records in Marketing Cloud Next Using Bulk API 2.0","body":"Creating records using Bulk API 2.0 involves a few distinct steps. First, organize your data in a CSV file. Next, send a POST request to create a bulk ingestion job, which provides you with a job ID. Use the job ID to send a PUT request that contains your CSV data. When you finish uploading data, send a PATCH request to change the status of the job and begin processing records.\n\nYou can use Bulk API 2.0 to create the record types shown in this table.\n\n| Record Type | API Name |\n| --- | --- |\n| Contact records | `Contact` |\n| Campaigns | `Campaign` |\n\nBefore you send any requests to Bulk API 2.0, obtain a bearer token. For more information, see [Connect to REST-based APIs](./mc-connect-apis-rest.md).\n\nUse target field names as the column headers in your CSV file. To retrieve a list of field names, issue a GET call to the `/services/data/{apiVersion}/sobjects/OBJECT_API_NAME/describe` endpoint, where `OBJECT_API_NAME` is the API name of the object to describe. Alternatively, you can view a list of fields in the Object Explorer on the Setup page of the Salesforce web app.\n\nThere are several other considerations to keep in mind when you create the CSV file. For more information, see [Prepare CSV Files](https://developer.salesforce.com/docs/atlas.en-us.api_asynch.meta/api_asynch/datafiles_prepare_csv.htm) in the _Bulk API 2.0 and Bulk API Developer Guide_.\n\nTo begin importing records in bulk, create a bulk ingestion job. Issue a POST request to the `/services/data/{apiVersion}/jobs/ingest` endpoint. The body of the request must contain at least two properties: `object` and `operation`. The value of the `object` property must match the API name of the record type that you’re inserting.\n\nSet the value of the `operation` to one of these values:\n\n*   `insert`—Use this value to create records.\n*   `update`—Use this value to update records.\n*   `upsert`—Use this value to update records when a match is found, or create records when no match is found.\n\nThis example shows a request to create a job that ingests contacts in bulk. For additional information and code examples, see [createBulkContactIngestionJob](https://developer.salesforce.com/docs/marketing/marketing-cloud-growth/references/mc-bulk-contacts?meta=createBulkContactIngestionJob).\n\nIf the request is successful, the response includes an `id` value. This value is the job ID, which you use in subsequent operations.\n\nTo upload data, send a PUT request to the `/services/data/{apiVersion}/jobs/ingest/JOB_ID/batches` endpoint, where `JOB_ID` is your ingestion job ID. Include your data in CSV format in the body of your request. For best results, limit the size of the data to 100 MB. For more information and code examples, see [uploadContactData](https://developer.salesforce.com/docs/marketing/marketing-cloud-growth/references/mc-bulk-contacts?meta=uploadContactData).\n\nFor general considerations related to uploading data using Bulk API 2.0, see [Upload Job Data](https://developer.salesforce.com/docs/atlas.en-us.api_asynch.meta/api_asynch/upload_job_data.htm) in the _Bulk API 2.0 and Bulk API Developer Guide_.\n\nChange the status of the job to `UploadComplete`. This step tells the system to start processing the uploaded data. You can change the status by sending a PATCH request to the `/services/data/{apiVersion}/jobs/ingest/{jobId}` endpoint. The body of the request must be a JSON object with a single property named `state` with a value of `uploadComplete`.\n\nTo end an ingestion job without processing any records, change the value of `state` to `aborted`.\n\nFor more information and code examples, see [closeBulkContactIngestionJob](https://developer.salesforce.com/docs/marketing/marketing-cloud-growth/references/mc-bulk-contacts?meta=closeBulkContactIngestionJob).\n\nCheck the status of the ingestion job by sending a GET request to the `/services/data/{apiVersion}/jobs/ingest/JOB_ID` endpoint, where `JOB_ID` is the job ID for the ingestion job. If the request is successful, the response includes a `status` property, which describes the current state of the job. For more information about retrieving the status of a job, see [getBulkContactIngestionJob](https://developer.salesforce.com/docs/marketing/marketing-cloud-growth/references/mc-bulk-contacts?meta=getBulkContactIngestionJob).\n\nYou can also retrieve lists of records that were successfully ingested, that failed to be ingested, or that haven’t been ingested yet.\n\n*   [getSuccessfulRecords](https://developer.salesforce.com/docs/marketing/marketing-cloud-growth/references/mc-bulk-contacts?meta=getSuccessfulRecords)\n*   [getFailedRecords](https://developer.salesforce.com/docs/marketing/marketing-cloud-growth/references/mc-bulk-contacts?meta=getFailedRecords)\n*   [getUnprocessedRecords](https://developer.salesforce.com/docs/marketing/marketing-cloud-growth/references/mc-bulk-contacts?meta=getUnprocessedRecords)"},{"id":"mc-manage-objects-create-rest.md#0","file":"mc-manage-objects-create-rest.md","relativePath":"mc-manage-objects-create-rest.md","heading":"Create Records in Marketing Cloud Next Using REST API","body":"Create individual records using the [sObjects create](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_sobject_basic_info_post.htm) endpoints in REST API.\n\nA common use case for this API is the integration of applications that collect contact registration information. You can use this API to feed the collected data directly into lead, contact, and campaign records.\n\nUse REST API to create the record types shown in this table.\n\n| Record Type | API Name |\n| --- | --- |\n| Contact records | `Contact` |\n| Lead records | `Lead` |\n| Campaigns | `Campaign` |\n\nBefore you send a request to REST API, obtain a bearer token. For more information, see [Connect to REST-based APIs](./mc-connect-apis-rest.md).\n\nTo create a record, send a POST request to the `/services/data/{apiVersion}/sobjects/OBJECT_API_NAME` endpoint, where `OBJECT_API_NAME` is the API name of the type of object that you want to create. The body of the request is a JSON object that contains the information to include in the record.\n\nA common use case is to use REST API to create individual contact records. This code example shows how to create a basic contact record.\n\nThe field names that you specify in the request body must exactly match the field names in the target object. You can retrieve a list of field names and relationships by issuing a GET call to the `/services/data/{apiVersion}/sobjects/OBJECT_API_NAME/describe` endpoint. Alternatively, you can view a list of fields and relationships in the Object Explorer on the Setup page of the Salesforce web app.\n\nFields that are required by the target object but not specified in the request receive the default values for the object. If a field in the request doesn’t exist in the target object, the request fails with an error.\n\nFor more information and code examples, see [createContact](https://developer.salesforce.com/docs/marketing/marketing-cloud-growth/references/mc-rest-contacts?meta=createContact).\n\nYou can create up to 200 records in a single synchronous operation by issuing a POST request to the `/services/data/{apiVersion}/composite/tree/OBJECT_API_NAME` endpoint. To create more than 200 records, use [Bulk API 2.0](./mc-manage-objects-create-bulk.md) instead.\n\nIn a request to create multiple records, the body of the request contains an array called `records`. Each record is a separate object in the array. Each record includes an additional object, `attributes`, which specifies the object type. The object must also include a `referenceId`, which is included in the response so that you can track which items were processed successfully.\n\nThis code example shows how to create multiple contact records in a single call to REST API.\n\nIf the request is successful, the response indicates whether there were errors in processing the request. It also lists the IDs and the reference IDs for each object that was created.\n\n*   _REST API Developer Guide_: [Create Multiple Records](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/dome_composite_sobject_tree_flat.htm)"},{"id":"mc-manage-objects-create-streaming-data-cloud.md#0","file":"mc-manage-objects-create-streaming-data-cloud.md","relativePath":"mc-manage-objects-create-streaming-data-cloud.md","heading":"Stream Records to Data Cloud API","body":"Data Cloud API supports streaming ingestion of contact records. Stream data to keep a source system in sync with Marketing Cloud Next in near real-time.\n\nTo stream data from an external source, create an ingestion API schema and connector, deploy a data stream, and then create a connected app.\n\n*   [Create an ingestion API schema file](https://developer.salesforce.com/docs/data/data-cloud-int/guide/c360-a-ingestion-api-schema-req.html)\n*   [Create an ingestion API connector](https://developer.salesforce.com/docs/data/data-cloud-int/guide/c360-a-connect-an-ingestion-source.html)\n*   [Create and deploy a data stream](https://help.salesforce.com/s/articleView?id=data.c360_a_data_ingestion.htm)\n*   [Create a connected app](https://help.salesforce.com/s/articleView?id=xcloud.connected_app_create.htm)\n\nConfigure your app to package the streaming data in a way that matches the schema for the ingestion API. A streaming ingestion request can contain multiple records, but the entire payload must be 200 KB or less.\n\nEach record that you want to add must be an object in an array called `data`. All of the fields defined in the schema must be present in the request payload, including optional fields. If there’s no data for a field, pass an empty string or `null`.\n\nObtain an authorization token, and then exchange it for a Data Cloud token. For more information, see [Obtain a Data Cloud access token](./mc-connect-apis-data-cloud.md).\n\nUse [synchronous record validation](https://developer.salesforce.com/docs/atlas.en-us.c360a_api.meta/c360a_api/c360a_api_synchronous_record_validation.htm) to ensure that your request includes the correct syntax and data types.\n\nTo validate the records, send them in a POST request to the `/api/v1/ingest/sources/DATA_SOURCE_NAME/DATA_SCHEMA/actions/test` endpoint.\n\nIf there are errors in the request, the response includes information about the issue that caused the error. Address the issues, and then resubmit the data to the validation endpoint. Repeat this process until the response indicates that there are no issues.\n\nWhen the API responds with a `200 OK` message, you’re ready to send the ingestion request.\n\nWhen your data is properly configured, you can submit it to the Ingestion API. Issue a POST request to the `/api/v1/ingest/sources/DATA_SOURCE_NAME/DATA_SCHEMA` endpoint.\n\nIf the API accepts the data, it responds with a `202 Accepted` response."},{"id":"mc-manage-objects-create.md#0","file":"mc-manage-objects-create.md","relativePath":"mc-manage-objects-create.md","heading":"mc-manage-objects-create","body":"# Create Records in Marketing Cloud\n\nUse REST API to create individual records synchronously, or use Bulk API 2.0 to create thousands of records asynchronously.\n\n*   [Create Records Using REST API](./mc-manage-objects-create-rest.md)\n*   [Create Multiple Records Using Bulk API 2.0](./mc-manage-objects-create-bulk.md)\n*   [Stream Records to Data Cloud API](./mc-manage-objects-create-streaming-data-cloud.md)"},{"id":"mc-manage-objects-delete-bulk.md#0","file":"mc-manage-objects-delete-bulk.md","relativePath":"mc-manage-objects-delete-bulk.md","heading":"Delete Multiple Records in Marketing Cloud Next Using Bulk API 2.0","body":"Use Bulk API 2.0 to delete thousands of records asynchronously.\n\nThis table shows the relevant record types that you can delete using Bulk API 2.0.\n\n| Record Type | API Name |\n| --- | --- |\n| Contact records | `Contact` |\n| Lead records | `Lead` |\n| Campaigns | `Campaign` |\n| Segments | `MarketSegment` |\n| Flows | `FlowRecord` |\n\nBefore you send a request to Bulk API 2.0, obtain a bearer token. For more information, see [Connect to REST-based APIs](./mc-connect-apis-rest.md).\n\nTo delete records in bulk, you must first create a CSV file that lists the IDs of the records you want to delete. Bulk deletion requests can include only the `Id` field. This behavior is different from other requests in Bulk API 2.0.\n\nThe first line of the CSV file must contain the text `Id`. Each line after that contains the ID of each record that you want to delete, as shown in this example.\n\nTo begin the process of deleting records in bulk, create a bulk ingestion job. Issue a POST request to the `/services/data/{apiVersion}/jobs/ingest` endpoint. The body of the request must contain at least two properties: `object` and `operation`. The value of the `object` property must match the API name of the record type that you’re deleting. The value of the `operation` property must be `delete`.\n\nThis example shows a request to create a job that deletes Contacts in bulk.\n\nIf the request is successful, the response includes an `id` value. This value is the job ID, which you use in subsequent operations.\n\nTo upload data, send a PUT request to the `/services/data/{apiVersion}/jobs/ingest/JOB_ID/batches` endpoint, where `JOB_ID` is your ingestion job ID. Include your data in CSV format in the body of the request. For best results, limit the size of the data to 100 MB.\n\nFor general considerations related to uploading data using Bulk API 2.0, see [Upload Job Data](https://developer.salesforce.com/docs/atlas.en-us.api_asynch.meta/api_asynch/upload_job_data.htm) in the _Bulk API 2.0 and Bulk API Developer Guide_.\n\nWhen you finish uploading data, change the status of the job to `UploadComplete`. This step tells the system to start processing the uploaded data. You can change the status by sending a PATCH request to the `/services/data/{apiVersion}/jobs/ingest/{jobId}` endpoint. The body of the request must be a JSON object with a single property named `state` with a value of `uploadComplete`.\n\nTo end an ingestion job without processing any records, change the value of `state` to `aborted`.\n\nCheck the status of the ingestion job by sending a GET request to the `/services/data/{apiVersion}/jobs/ingest/JOB_ID` endpoint, where `JOB_ID` is the job ID for the ingestion job. If the request is successful, the response includes a `status` property, which describes the current state of the job."},{"id":"mc-manage-objects-delete-rest.md#0","file":"mc-manage-objects-delete-rest.md","relativePath":"mc-manage-objects-delete-rest.md","heading":"Delete Records in Marketing Cloud Next Using REST API","body":"You can delete individual records using the [delete sObject rows](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_sobject_retrieve_delete.htm) endpoints in REST API.\n\nYou can use REST API to delete these record types.\n\n| Record Type | API Name |\n| --- | --- |\n| Contact records | `Contact` |\n| Lead records | `Lead` |\n| Campaigns | `Campaign` |\n| Marketing segments | `MarketSegment` |\n| Flows | `FlowRecord` |\n\nBefore you send a request to REST API, obtain a bearer token. For more information, see [Connect to REST-based APIs](./mc-connect-apis-rest.md).\n\nIf you don’t know the IDs of the records that you want to delete, [perform a query](./mc-manage-objects-query.md).\n\nTo delete a record, send a DELETE request to the `/data/{apiVersion}/sobjects/OBJECT_API_NAME/RECORD_ID` endpoint. Replace `OBJECT_API_NAME` with the API name of the type of object that you want to delete, and replace `RECORD_ID` with the unique ID of the record to delete. You can find the IDs for the records that you want to delete by [running a query](./mc-manage-objects-query.md).\n\nThis example shows how to delete a marketing segment. The DELETE operation doesn’t contain a request body.\n\nWhen the record is deleted successfully, the API returns a `204 No Content` response with no response body."},{"id":"mc-manage-objects-delete.md#0","file":"mc-manage-objects-delete.md","relativePath":"mc-manage-objects-delete.md","heading":"mc-manage-objects-delete","body":"# Delete Records in Marketing Cloud\n\nBoth REST API and Bulk API 2.0 support the deletion of records. Issue a DELETE request to delete up to 2,000 endpoints synchronously using REST API. Alternatively, use Bulk API 2.0 to delete thousands of records asynchronously.\n\n*   [Delete Records Using REST API](./mc-manage-objects-delete-rest.md)\n*   [Delete Multiple Records Using Bulk API 2.0](./mc-manage-objects-delete-bulk.md)"},{"id":"mc-manage-objects-get-rest.md#0","file":"mc-manage-objects-get-rest.md","relativePath":"mc-manage-objects-get-rest.md","heading":"Get Marketing Cloud Next Records Using REST API","body":"Retrieve individual records using the [get sObject rows](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_sobject_retrieve_get.htm) endpoints in REST API.\n\nYou can use REST API to retrieve many types of records. This table shows the record types that are most relevant to Marketing Cloud.\n\n| Record Type | API Name |\n| --- | --- |\n| Contact records | `Contact` |\n| Lead records | `Lead` |\n| Campaigns | `Campaign` |\n| Marketing segments | `MarketSegment` |\n| Flows | `FlowRecord` |\n| Content workspaces | `ManagedContentSpace` |\n| Content items | `ManagedContent` |\n\nBefore you send a request to REST API, obtain a bearer token. For more information, see [Connect to REST-based APIs](./mc-connect-apis-rest.md).\n\nTo retrieve a record, send a GET request to `/services/data/{apiVersion}/sobjects/OBJECT_API_NAME/RECORD_ID`. Replace `OBJECT_API_NAME` with the API name of the type of object that you want to retrieve, and replace `RECORD_ID` with the record ID.\n\nIf the request is successful, the response body varies depending on the object type of the record that you retrieved. This example shows a response body for a Flow record."},{"id":"mc-manage-objects-get.md#0","file":"mc-manage-objects-get.md","relativePath":"mc-manage-objects-get.md","heading":"mc-manage-objects-get","body":"# Get Records in Marketing Cloud\n\nUse REST API to retrieve individual records synchronously.\n\nBulk API 2.0 doesn’t include operations for retrieving specific records. However, you can use it to [perform queries that retrieve information about multiple records](./mc-manage-objects-query.md).\n\n*   [Get Records Using REST API](./mc-manage-objects-get-rest.md)"},{"id":"mc-manage-objects-query-bulk.md#0","file":"mc-manage-objects-query-bulk.md","relativePath":"mc-manage-objects-query-bulk.md","heading":"Query Objects in Marketing Cloud Next Using Bulk API 2.0","body":"For complex queries, or queries that you expect to produce a large set of results, use Bulk API 2.0. Bulk API 2.0 executes queries asynchronously.\n\nBefore you issue a query request, create a SOQL statement that specifies the data that you want to retrieve. Remove any line breaks from your SOQL statement. For more information, see [Understand SOQL Queries](./mc-manage-objects-query-soql.md).\n\nBulk queries don’t support the complete set of SOQL clauses and functions. For more information, see [Create a Query Job](https://developer.salesforce.com/docs/atlas.en-us.api_asynch.meta/api_asynch/query_create_job.htm) in the _Bulk API 2.0 and Bulk API Developer Guide_.\n\nTo create a bulk query job, issue a POST request to the `/services/data/{apiVersion}/jobs/query` endpoint. For more information about the properties of the request body, see [Create a Query Job](https://developer.salesforce.com/docs/atlas.en-us.api_asynch.meta/api_asynch/query_create_job.htm) in the _Bulk API 2.0 and Bulk API Developer Guide_.\n\nIf the request is successful, the response includes the job ID (`id`), which you use to check the status of the request and to retrieve the resulting data.\n\nTo check the status of a bulk query, issue a GET request to the `/data/{apiVersion}/jobs/query/JOB_ID` endpoint, replacing `JOB_ID` with the unique ID of the query job.\n\nWhen the status of the query job is `JobComplete`, the query has finished running and your data is ready to retrieve.\n\nTo retrieve the query results, issue a GET request to the `/data/{apiVersion}/jobs/query/JOB_ID/results` endpoint.\n\nIf the request is successful, the response includes the resulting data in the requested format, as shown in this example."},{"id":"mc-manage-objects-query-rest.md#0","file":"mc-manage-objects-query-rest.md","relativePath":"mc-manage-objects-query-rest.md","heading":"Query Objects in Marketing Cloud Next Using REST API","body":"REST API provides a simple method for executing basic queries synchronously. If the complexity of the query or the quantity of results causes your queries to timeout, consider running them [asynchronously using Bulk API 2.0](./mc-manage-objects-query-bulk.md).\n\nBefore you issue a query request, create a SOQL statement that defines the data that you want to retrieve. For more information, see [Understand SOQL Queries](./mc-manage-objects-query-soql.md).\n\nAfter you create a SOQL statement, remove all of the line breaks, and replace every space in the query with `%20`.\n\nIssue a GET request to the `/services/data/{apiVersion}/query` endpoint, with your SOQL query included as a query string.\n\nIf the request is successful, the response includes a list of contacts that match your query."},{"id":"mc-manage-objects-query-soql.md#0","file":"mc-manage-objects-query-soql.md","relativePath":"mc-manage-objects-query-soql.md","heading":"mc-manage-objects-query-soql","body":"# Understand SOQL Queries\n\nSOQL is a query language that’s similar to SQL but designed for Salesforce data. To query data using Salesforce APIs, create a SOQL statement that defines the information you want to search for.\n\nThe basic structure of a SOQL statement resembles this example.\n\nFor example, this SOQL query returns the value of the `Id`, `FirstName`, `LastName`, and `Country` fields for all contacts where the value of the MailingCountry field is `NG`. Results are returned in ascending order by `LastName`, and then in ascending order by `FirstName`. The maximum number of results returned is 25.\n\n*   [SOQL and SOSL Reference](https://developer.salesforce.com/docs/atlas.en-us.soql_sosl.meta/soql_sosl/sforce_api_calls_soql_sosl_intro.htm)"},{"id":"mc-manage-objects-query.md#0","file":"mc-manage-objects-query.md","relativePath":"mc-manage-objects-query.md","heading":"mc-manage-objects-query","body":"# Query Records in Marketing Cloud\n\nSalesforce REST API and Bulk API 2.0 include operations for querying records. The `query` endpoint in REST API provides results synchronously, making it a useful tool for small queries. For more complex queries, or queries that potentially involve a large number of results, the asynchronous Bulk API 2.0 is a better choice.\n\n*   [Understand SOQL Queries](./mc-manage-objects-query-soql.md)\n*   [Query Objects Using REST API](./mc-manage-objects-query-rest.md)\n*   [Query Objects Using Bulk API 2.0](./mc-manage-objects-query-bulk.md)"},{"id":"mc-manage-objects-update-bulk.md#0","file":"mc-manage-objects-update-bulk.md","relativePath":"mc-manage-objects-update-bulk.md","heading":"Update or Upsert Multiple Records Using Bulk API 2.0","body":"With Bulk API 2.0, you can perform update or upsert operations on thousands of records asynchronously. An upsert operation updates existing records and creates records when matching records aren’t found.\n\nYou can use Bulk API 2.0 to update the record types shown in this table.\n\n| Record Type | API Name |\n| --- | --- |\n| Contact records | `Contact` |\n| Lead records | `Lead` |\n| Campaigns | `Campaign` |\n\nBefore you send any requests to Bulk API 2.0, obtain a bearer token. For more information, see [Connect to REST-based APIs](./mc-connect-apis-rest.md).\n\nCreate a CSV file that contains the information that you want to update or upsert. The CSV file must include an `Id` column that contains the ID for each contact that you want to update. If you’re performing an upsert operation, you must also include a column that contains a unique external ID.\n\nThe additional columns for each record contain the values that you want to update or upsert. The column names in your CSV file must match the field names in the target object exactly. You can retrieve a list of field names by issuing a GET call to the `/services/data/{apiVersion}/sobjects/OBJECT_API_NAME/describe` endpoint. Alternatively, you can view a list of fields in the Object Explorer on the Setup page of the Salesforce web app.\n\nThere are several other considerations to keep in mind when you create the CSV file. For more information, see [Prepare CSV Files](https://developer.salesforce.com/docs/atlas.en-us.api_asynch.meta/api_asynch/datafiles_prepare_csv.htm) in the _Bulk API 2.0 and Bulk API Developer Guide_.\n\nWhen you’re ready to bring your data into Marketing Cloud, create a bulk ingestion job. The structure of the request body varies depending on whether you want to perform an update or an upsert operation.\n\nTo perform an update operation, issue a POST request to the `/services/data/{apiVersion}/jobs/ingest` endpoint. The body of the request must contain at least two properties: `object` and `operation`. The value of the `object` property must match the API name of the record type that you want to update. The value of the `operation` property must be `update` or `upsert`.\n\nThis example shows a minimal request to create a job that updates contacts in bulk. For additional information and code examples, see [createBulkContactIngestionJob](https://developer.salesforce.com/docs/marketing/marketing-cloud-growth/references/mc-bulk-contacts?meta=createBulkContactIngestionJob).\n\nTo perform an upsert operation, the body of the request must also include the `externalIdFieldName` property. The value of this property must equal the field name of an external ID on the target object. To learn more about external IDs, see [Differences between the 'External ID' field and the 'Unique ID' field setting](https://help.salesforce.com/s/articleView?id=000385174&type=1). This example shows a basic request to create a bulk upsert job.\n\nIf the request is successful, the response includes an `id` value. This value is the job ID, which you use in subsequent operations.\n\nTo upload data, send a PUT request to the `/services/data/{apiVersion}/jobs/ingest/JOB_ID/batches` endpoint, where `JOB_ID` is your job ID. Include your data in CSV format in the body of the request. For best results, limit the size of the data to 100 MB.\n\nFor more information about uploading contact data, see [uploadContactData](https://developer.salesforce.com/docs/marketing/marketing-cloud-growth/references/mc-bulk-contacts?meta=uploadContactData).\n\nFor general considerations related to uploading data using Bulk API 2.0, see [Upload Job Data](https://developer.salesforce.com/docs/atlas.en-us.api_asynch.meta/api_asynch/upload_job_data.htm) in the _Bulk API 2.0 and Bulk API Developer Guide_.\n\nWhen you finish uploading your data, change the status of the job to `UploadComplete`. This step tells Salesforce to begin processing the data. You can change the status by sending a PATCH request to the `/services/data/{apiVersion}/jobs/ingest/{jobId}` endpoint. The body of the request must be a JSON object with a single property named `state` with a value of `uploadComplete`.\n\nTo end a bulk update job without processing any records, change the value of `state` to `aborted`.\n\nFor more information and code examples, see [closeBulkContactIngestionJob](https://developer.salesforce.com/docs/marketing/marketing-cloud-growth/references/mc-bulk-contacts?meta=closeBulkContactIngestionJob).\n\nCheck the status of the bulk update job by sending a GET request to the `/services/data/{apiVersion}/jobs/ingest/JOB_ID` endpoint, where `JOB_ID` is the job ID. If the request is successful, the response includes a `status` property, which describes the current state of the job. For more information about retrieving the status of a job, see [getBulkIngestionJob](https://developer.salesforce.com/docs/marketing/marketing-cloud-growth/references/mc-bulk-contacts?meta=getBulkContactIngestionJob).\n\nYou can also retrieve lists of records that were [successfully updated](https://developer.salesforce.com/docs/marketing/marketing-cloud-growth/references/mc-bulk-contacts?meta=getSuccessfulRecords), that [failed to be updated](https://developer.salesforce.com/docs/marketing/marketing-cloud-growth/references/mc-bulk-contacts?meta=getFailedRecords), or that [haven’t been updated yet](https://developer.salesforce.com/docs/marketing/marketing-cloud-growth/references/mc-bulk-contacts?meta=getUnprocessedRecords). These examples show you how to retrieve this information for contacts. For other object types, replace “contact” in the URL endpoints with the API name of the object type that you want to retrieve results for."},{"id":"mc-manage-objects-update-rest.md#0","file":"mc-manage-objects-update-rest.md","relativePath":"mc-manage-objects-update-rest.md","heading":"mc-manage-objects-update-rest","body":"You can update records using the [sObjects rows](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_sobject_retrieve_patch.htm) endpoints in REST API.\n\nYou can use REST API to update the record types shown in this table.\n\n| Record Type | API Name |\n| --- | --- |\n| Contact records | `Contact` |\n| Campaigns | `Campaign` |\n\nBefore you send a request to REST API, obtain a bearer token. For more information, see [Connect to REST-based APIs](./mc-connect-apis-rest.md).\n\nTo update a record, send a PATCH request to the `/data/{apiVersion}/sobjects/OBJECT_API_NAME/RECORD_ID` endpoint. Replace `OBJECT_API_NAME` with the API name of the type of object that you want to update, and replace `RECORD_ID` with the unique ID of the record to update. To find IDs for the records that you want to update, [run a query](./mc-manage-objects-query.md).\n\nThe body of the request is a JSON object that contains the information that you want to update for the object. This example changes the value of the `MobilePhone` property for a contact.\n\nThe field names that you specify in the request body must exactly match the field names in the target object. You can retrieve a list of field names and relationships by issuing a GET call to the `/services/data/{apiVersion}/sobjects/OBJECT_API_NAME/describe` endpoint. Alternatively, you can view a list of fields and relationships in the Object Explorer on the Setup page of the Salesforce web app.\n\nFields that are already present in the record but not specified in the request are unchanged. If a field in the request body doesn’t exist in the target object, the request fails with an error.\n\nIf the request is successful, the response contains a JSON object with a complete list of fields and values for the updated record.\n\nFor more information and code examples, see [updateContact](https://developer.salesforce.com/docs/marketing/marketing-cloud-growth/references/mc-rest-contacts?meta=updateContact)."},{"id":"mc-manage-objects-update.md#0","file":"mc-manage-objects-update.md","relativePath":"mc-manage-objects-update.md","heading":"mc-manage-objects-update","body":"# Update Records in Marketing Cloud\n\nUse REST API to update individual records synchronously, or use Bulk API 2.0 to update thousands of records asynchronously.\n\n*   [Update Records Using REST API](./mc-manage-objects-update-rest.md)\n*   [Update or Upsert Multiple Records Using Bulk API 2.0](./mc-manage-objects-update-bulk.md)"},{"id":"mc-manage-objects.md#0","file":"mc-manage-objects.md","relativePath":"mc-manage-objects.md","heading":"Manage Records in Marketing Cloud","body":"An _object_ is a data structure that contains a specific category of data. An object is made up of several _fields_. Think of objects as databases and fields as the columns within that database. Each row in the database is a _record_. As a developer, you interact with several of these elements.\n\nEach object has a unique API name. When you use an API to interact with your Salesforce data, you provide the API name of the object that you want to interact with. REST API endpoints typically follow the format `/services/data/{apiVersion}/sobjects/OBJECT_API_NAME...`, where `OBJECT_API_NAME` is the API name of the object that you’re interacting with. For example, to create a contact, you send a POST request to `/services/data/{apiVersion}/sobjects/contact`. In Bulk API 2.0, the body of your request to create a job contains the API name of the object that you want to interact with.\n\n*   [Get Records](./mc-manage-objects-get.md)\n*   [Create Records](./mc-manage-objects-create.md)\n*   [Update Records](./mc-manage-objects-update.md)\n*   [Query Records](./mc-manage-objects-query.md)\n*   [Delete Records](./mc-manage-objects-delete.md)"},{"id":"mc-manage-segments-get-details.md#0","file":"mc-manage-segments-get-details.md","relativePath":"mc-manage-segments-get-details.md","heading":"Get Marketing Cloud Next Segment Details","body":"Retrieve details of an individual segment using the [Data Cloud Segment](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_cdp_ssot_segment.htm) endpoint in Connect API.\n\nBefore you send a request to Connect API, obtain a bearer token. For more information, see [Connect to REST-based APIs](./mc-connect-apis-rest.md).\n\nTo retrieve information about a segment, send a GET request to the `/services/data/{apiVersion}/ssot/segments/SEGMENT_API_NAME` endpoint. Replace `SEGMENT_API_NAME` with the API name of the segment that you want to retrieve details for. For additional information and code examples, see [getSegmentDetails](https://developer.salesforce.com/docs/marketing/marketing-cloud-growth/references/mc-connect-segments?meta=getSegmentDetails).\n\nIf the request is successful, the response body contains detailed information about the specified segment."},{"id":"mc-manage-segments-get-members.md#0","file":"mc-manage-segments-get-members.md","relativePath":"mc-manage-segments-get-members.md","heading":"Get Marketing Cloud Next Segment Members","body":"Retrieve a list of members in a segment by using the [Data Cloud Segment Members](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_cdp_ssot_segment_members.htm) endpoint in Connect API.\n\nBefore you send a request to Connect API, obtain a bearer token. For more information, see [Connect to REST-based APIs](./mc-connect-apis-rest.md).\n\nTo retrieve a list of segment members, send a GET request to the `/services/data/{apiVersion}/ssot/segments/SEGMENT_API_NAME/members` endpoint. Replace `SEGMENT_API_NAME` with the API of the segment that you want to retrieve a list of members for.\n\nIf the request is successful, the response body contains a list of segment members.\n\nYou can filter, sort, and limit the results by adding query parameters. For information and code examples, see [getSegmentMembers](https://developer.salesforce.com/docs/marketing/marketing-cloud-growth/references/mc-connect-segments?meta=getSegmentMembers)."},{"id":"mc-manage-segments-get.md#0","file":"mc-manage-segments-get.md","relativePath":"mc-manage-segments-get.md","heading":"mc-manage-segments-get","body":"# Get Segments in Marketing Cloud\n\nRetrieve a list of segments using the [Data Cloud Segments](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_cdp_ssot_segments.htm) endpoint in Connect API.\n\nBefore you send a request to Connect API, obtain a bearer token. For more information, see [Connect to REST-based APIs](./mc-connect-apis-rest.md).\n\nTo retrieve a list of segments, send a GET request to the `/services/data/{apiVersion}/ssot/segments` endpoint. For additional information and code examples, see [getSegments](https://developer.salesforce.com/docs/marketing/marketing-cloud-growth/references/mc-connect-segments?meta=getSegments).\n\nIf the request is successful, the response body contains a list of segments in your org."},{"id":"mc-manage-segments-publish.md#0","file":"mc-manage-segments-publish.md","relativePath":"mc-manage-segments-publish.md","heading":"Publish a Marketing Cloud Next Segment","body":"Publish an individual segment using the [Data Cloud Segment Publish](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_cdp_ssot_segment_publish.htm) endpoint in Connect API.\n\nBefore you send a request to Connect API, obtain a bearer token. For more information, see [Connect to REST-based APIs](./mc-connect-apis-rest.md).\n\nTo publish a segment, send a GET request to the `/services/data/{apiVersion}/ssot/segments/SEGMENT_ID/actions/publish` endpoint. Replace `SEGMENT_ID` with the ID of the segment that you want to publish. For additional information and code examples, see [publishSegment](https://developer.salesforce.com/docs/marketing/marketing-cloud-growth/references/mc-connect-segments?meta=publishSegment).\n\nThis POST request doesn’t accept a request body.\n\nIf the request is successful, the response body contains information about the request to publish the segment."},{"id":"mc-manage-segments.md#0","file":"mc-manage-segments.md","relativePath":"mc-manage-segments.md","heading":"mc-manage-segments","body":"# Manage Segments in Marketing Cloud\n\nSegments are targeted groups of recipients for your marketing communications. Use [Connect API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/intro_what_is_chatter_connect.htm) to retrieve, create, modify, and delete segments.\n\n*   [Get Segments](./mc-manage-segments-get.md)\n*   [Get Segment Details](./mc-manage-segments-get-details.md)\n*   [Get Segment Members](./mc-manage-segments-get-members.md)\n*   [Publish Segments](./mc-manage-segments-publish.md)"},{"id":"mc-manage-transactional-messages-on-demand-flow.md#0","file":"mc-manage-transactional-messages-on-demand-flow.md","relativePath":"mc-manage-transactional-messages-on-demand-flow.md","heading":"Send Transactional Messages Through On-Demand Flow","body":"API-triggered transactional messaging lets you send prioritized, personalized messages—such as one-time passwords (OTPs) or order confirmations from Marketing Cloud Next in real time. By invoking an **On-Demand Flow** through the REST API, you can securely pass dynamic data at send time and deliver time-sensitive service communications exactly when they’re needed.\n\nBefore you begin, make sure you have:\n\n*   Permissions to create Apex Classes, CMS Email content, Flows, and Connected Apps\n*   Ability to authenticate and invoke REST APIs\n*   A data source for personalization, such as an Apex class or Data Cloud data graphs\n\n> **Note:** Using Data Cloud data graphs may introduce additional latency.\n\nTo pass real-time personalization values into the email at send time, define a data source that the Flow and email can reference.\n\nIn this example, an Apex class defines the input structure for personalization fields such as first name and OTP code.\n\n1.   In **Setup**, enter **Apex Classes** in Quick Find.\n2.   Click **New**.\n3.   Create an Apex Class that defines the required input variables required for the transactional message.\n4.   Save the class. The Apex Class exposes variables that are later mapped in the Flow and populated through the REST API request.\n\nCreate transactional email content as CMS content and configure it with the correct data source.\n\n1.   Create the Email: \n    1.   Go to **Marketing App > Content**.\n    2.   Click **Add CMS Content** and select **Email**.\n    3.   Open the email in **Email Builder**.\n\n2.   Connect the data source: \n    1.   In the Email Builder, add a new data source and select **Apex Data Provider**.\n    2.   Choose the Apex Class you created.\n\n3.   Design the email body: \n    1.   Insert merge fields (for example, FirstName or otpCode) from the Apex Data Provider.\n    2.   Set **Message Purpose** to **Transactional**.\n    3.   Save and publish the email.\n\nCMS channels represent publishing endpoints such as email, and you must publish transactional emails before using them in a Flow.\n\nThe REST API calls the On-Demand Flow, which defines the send logic.\n\n1.   Create the Flow: \n    1.   Go to the **Flow** tab and click **New**.\n    2.   Select **On-Demand Flow** (launched by REST API).\n\n2.   Add the Apex resource: \n    1.   In the Toolbox, click New **Resource**.\n    2.   Set **Resource Type** to **Variable**.\n    3.   Set **Data Type** to **Apex-Defined**.\n    4.   Select your personalization class as the Apex Class.\n    5.   Enable **Available for Input**. Save the API Name of this resource. You’ll need it when constructing the REST API request.\n\n3.   Add **Send Email** as the first Flow element.\n4.   Select the published transactional email.\n5.   Configure the sender and activate the Flow.\n6.   Save and activate the Flow.\n\nTo invoke the Flow, you must authenticate using OAuth and then call the Flow action endpoint.\n\n1.   In Setup, search for **External Client App**.\n2.   Open **App Manager** and click **New App**.\n3.   Enter basic information (Name, API Name, Contact Email).\n4.   Enable **OAuth Settings**.\n5.   Enter a Callback URL.\n6.   Add these OAuth scopes: \n    *   Full access (full)\n    *   Manage user data via APIs (api)\n\n7.   Save the app.\n\nAfter saving, open **Manage Consumer Details** and record the **Consumer Key** and **Consumer Secret**."},{"id":"mc-manage-transactional-messages.md#0","file":"mc-manage-transactional-messages.md","relativePath":"mc-manage-transactional-messages.md","heading":"mc-manage-transactional-messages","body":"# Manage Transactional Messages\n\nTransactional messages deliver time-sensitive information such as one-time passwords, confirmations, and service notifications to customers. You can create, personalize, and control how these messages are sent to ensure secure, reliable delivery.\n\n*   [Send Transactional Messages Through On-Demand Flow](./mc-manage-transactional-messages-on-demand-flow.md)"},{"id":"mc-resources-documentation.md#0","file":"mc-resources-documentation.md","relativePath":"mc-resources-documentation.md","heading":"Marketing Cloud Next Documentation Resources","body":"There are several documentation resources that are relevant to Marketing Cloud Next users and developers.\n\nThe [help documentation](https://help.salesforce.com/s/articleView?id=mktg.mktg_main.htm) provides information about setting up and using Marketing Cloud.\n\nData Cloud is a Salesforce application that you can use to ingest, store, harmonize, segment, and query all of your data. Marketing Cloud Next tightly integrates with Data Cloud to manage customer profiles, consent, marketing assets, campaign metrics, and more.\n\n*   The [Data Cloud Developer Guide](https://developer.salesforce.com/docs/platform/data-cloud-dev/guide/get-started.html) provides context into the APIs and SDKs that you can use to create custom applications using Data Cloud.\n*   The [Data Cloud Reference Guide](https://developer.salesforce.com/docs/atlas.en-us.c360a_api.meta/c360a_api/c360a_api_intro_cdpapis.htm) contains reference information related to Data Cloud Direct APIs. It also provides detailed information about the standard data model objects (DMOs) used in Data Cloud.\n*   The [Data Cloud Resources section of the Connect REST API Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_customer_360_audiences_resources.htm) describes the Connect REST API resources that apply to Data Cloud. Use Connect API to query data and metadata. You can also use it to manage segment publication, identity resolution rulesets, and calculated insights. Connect API has relaxed authentication requirements relative to the Direct API.\n\nThe Salesforce Platform APIs are helpful for querying and managing your Salesforce data.\n\n*   [REST API Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/intro_what_is_rest_api.htm) contains guidance and reference content for the Salesforce REST API, which uses HTTP-based APIs.\n*   [Bulk API 2.0 Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.api_asynch.meta/api_asynch/bulk_api_2_0.htm) provides information about the Bulk API 2.0. Use this REST-based API when you want to asynchronously create, modify, delete, or query a large volume of data.\n*   [SOAP API Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.api.meta/api/sforce_api_quickstart_intro.htm) describes the usage and operations of SOAP API.\n*   [Tooling API Reference](https://developer.salesforce.com/docs/atlas.en-us.api_tooling.meta/api_tooling) contains reference content for Tooling API, which you use to build and modify Lightning components such as flows.\n*   [Metadata API Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.220.0.api_meta.meta/api_meta/meta_intro.htm) describes how you can use Metadata API to retrieve, deploy, create, update, or delete customization information. In Marketing Cloud, you can use Metadata to programmatically manage flows.\n\nThe [Object Reference for the Salesforce Platform](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_concepts.htm) contains information about the standard objects and fields that exist in every Salesforce org.\n\nThe [SOQL and SOSL Reference](https://developer.salesforce.com/docs/atlas.en-us.soql_sosl.meta/soql_sosl/) contains information about the syntax, limits, and performance considerations for Salesforce Object Query Language (SOQL) and Salesforce Object Search Language (SOSL). SOQL is a SQL-like query language that you can use to search for data in specific objects. SOSL is a programmatic way of searching for data across all objects and fields. You can execute SOQL queries in Bulk API 2.0, and both SOQL and SOSL queries in REST API.\n\nUse [Connect API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/) to upload files to your CMS workspace."},{"id":"mc-resources-tools.md#0","file":"mc-resources-tools.md","relativePath":"mc-resources-tools.md","heading":"Salesforce Platform Developer Tools","body":"Salesforce offers several tools that can help experienced developers and admins accelerate the development process.\n\nPostman is a popular tool for testing API calls. The [Salesforce Developers Postman workspace](https://www.postman.com/salesforce-developers/workspace/salesforce-developers) contains a complete collection of sample requests that you can use to interact with Salesforce APIs, including Data Cloud API.\n\nThe collection includes a folder labeled Salesforce Marketing Cloud APIs. This folder contains requests designed for Marketing Cloud Engagement, which is a separate product. The Marketing Cloud Engagement APIs aren’t compatible with Marketing Cloud Next. For more information about developing on Marketing Cloud Engagement, see [Marketing Cloud Engagement APIs and Programmatic Languages](https://developer.salesforce.com/docs/marketing/marketing-cloud/overview).\n\nSoapUI is a web-service testing application designed specifically for SOAP-based APIs. On the Setup page in the Salesforce user interface, you can generate a WSDL file that you can load into SoapUI. To see the steps involved in configuring SoapUI to work with the Salesforce Platform, see the [Use SOAP API](https://trailhead.salesforce.com/content/learn/modules/api_basics/api_basics_soap) module on Trailhead.\n\nSalesforce CLI is a command-line interface that provides an easy way to manage and automate your Salesforce orgs. For example, you can use the CLI to quickly create, read, update, and delete contact records. For more information, see [Install Salesforce CLI](https://developer.salesforce.com/docs/atlas.en-us.sfdx_setup.meta/sfdx_setup/sfdx_setup_install_cli.htm).\n\nDevelopers who build on the Salesforce Platform often use Visual Studio Code. The Salesforce Extension Packs provide helpful tools for interacting with Salesforce APIs and SDKs.\n\nBefore you install one of these extensions, install the Salesforce CLI and either [version 11](https://www.oracle.com/java/technologies/javase/jdk11-archive-downloads.html) or [version 17](https://www.oracle.com/java/technologies/downloads/#java17) of the Java Developer Kit (JDK).\n\nSalesforce Extension Pack\nThese tools provide features for working with development orgs (scratch orgs, sandboxes, and Developer Edition orgs), Apex, Aura components, and Visualforce.\n\nTo install the Extension Pack, search for “Salesforce Extension Pack” in the Visual Studio Code Extension Marketplace, and then click the **Install** button next to Salesforce Extension Pack.\n\nSalesforce Extension Pack (Expanded)\nThis expanded version of the Salesforce Extension Pack includes all of the extensions in the standard extension pack. It also includes several third-party extensions for formatting code, performing static analysis, and analyzing logs.\n\nTo install the Extension Pack, search for “Salesforce Extension Pack” in the Visual Studio Code Extension Marketplace, and then click the **Install** button next to Salesforce Extension Pack (Expanded)."},{"id":"mc-resources-trailhead.md#0","file":"mc-resources-trailhead.md","relativePath":"mc-resources-trailhead.md","heading":"Learning Resources for Marketing Cloud","body":"If you aren’t already familiar with development tools and processes on the Salesforce platform, there are several helpful learning resources available on [Trailhead](https://trailhead.salesforce.com/).\n\nIf you’re new to developing on the Salesforce platform, you can build a solid foundation by completing these modules.\n\n[Quick Start: Connect Postman to Salesforce](https://trailhead.salesforce.com/content/learn/projects/quick-start-connect-postman-to-salesforce)\nPostman is a tool used by developers, testers, and just about everybody else who interacts with REST-based APIs. In this module, you download and configure a Postman collection that makes it easy to experiment with the Salesforce Platform REST API and Bulk API.\n\n[Quick Start: Visual Studio Code for Salesforce Development](https://trailhead.salesforce.com/content/learn/projects/quickstart-vscode-salesforce)\nSet up Visual Studio Code as a Salesforce development environment.\n\n[Platform API Basics](https://trailhead.salesforce.com/content/learn/modules/api_basics)\nStart out with a tour of the Salesforce Platform APIs, and then learn how to use tools including Postman and SoapAPI to issue your first API requests.\n\nAfter you complete the basics, it’s time to build on your skills. By completing these modules, you broaden your understanding of important Salesforce Platform development concepts.\n\n[Platform Development Basics](https://trailhead.salesforce.com/content/learn/modules/platform-development-basics)\nLearn how to use Lightning Web Components, Apex, and Node.js to create custom interfaces, automate processes, and build scalable applications.\n\n[Object-Oriented Programming for Admins](https://trailhead.salesforce.com/content/learn/modules/object-oriented-programming-for-admins)\nEnhance your Salesforce data with Apex classes, objects, DML, sets, and loops.\n\n[SOQL for Admins](https://trailhead.salesforce.com/content/learn/modules/soql-for-admins)\nSOQL is a query language used to retrieve data from the Salesforce database. In this module, you learn about the components and syntax of a SOQL query. You also create and run your first SOQL query.\n\nMarketing Cloud Next is tightly integrated with Data Cloud, so it’s important to understand how Data Cloud works as you plan and configure your org.\n\n[Data Cloud-Powered Experiences](https://trailhead.salesforce.com/content/learn/modules/data-cloud-powered-experiences)\nThis introduction explains how you can use Data Cloud create personalized, real-time experiences across Salesforce and beyond.\n\n[Ingestion and Modeling in Data Cloud](https://trailhead.salesforce.com/content/learn/modules/customer-360-audiences-data-ingestion-and-modeling)\nLearn how to bring data into Data Cloud from external sources, and then harmonize that data with your existing data models.\n\n[Customer 360 Data Model for Data Cloud](https://trailhead.salesforce.com/content/learn/modules/customer-360-data-model-for-customer-data-platform)\nUnderstand the data model for Data Cloud, and learn how to create data model objects (DMOs)."},{"id":"mc-resources-videos.md#0","file":"mc-resources-videos.md","relativePath":"mc-resources-videos.md","heading":"Marketing Cloud Next Video Library","body":"The [Salesforce Developers channel on YouTube](https://www.youtube.com/c/salesforcedevelopers) contains videos that guide you through fundamental processes on the Salesforce platform.\n\nUnderstanding the Salesforce APIs is a key component of interacting with Marketing Cloud Next programmatically.\n\n[Success at Scale with Bulk API 2.0](https://www.youtube.com/watch?v=7Wl3LyT8OJc)\nExplore Bulk API 2.0 and learn how it can simplify your large-scale data workloads.\n\nOne of the things that makes Marketing Cloud Next so powerful is its relationship to Data Cloud. Marketing Cloud Next uses Data Cloud data model objects (DMOs) to store and manage marketing assets, customer consent tracking, campaign performance metrics, and more. You can also connect Data Cloud to other apps and services to stream and ingest data from them. These videos provide a helpful introduction to several important concepts in Data Cloud.\n\n[Creating Data Streams Using Salesforce CRM Connector](https://www.youtube.com/watch?v=tbGE71MEV4E)\nLearn what a Data Stream is and how to create a stream that ingests the contact data that you already have in Salesforce.\n\n[Using Ingestion API to Load Data Into Data Cloud](https://www.youtube.com/watch?v=3xWSVGcTORI)\nSee the complete process of bringing new data into Data Cloud. While the scenario covered in the video deals with ingesting data from physical devices, you can use the principles covered in the video to bring information about your customers into Data Cloud.\n\n[Using Web SDK to Capture Interactions on a Website](https://www.youtube.com/watch?v=HtNLQdsQECk)\nLearn how to use the Salesforce Interactions Web SDK to track your customers’ interactions with your web properties and mobile apps."},{"id":"mc-resources.md#0","file":"mc-resources.md","relativePath":"mc-resources.md","heading":"mc-resources","body":"# Additional Resources for Marketing Cloud\n\nMarketing Cloud Next brings the power of the Salesforce platform to your team’s marketing efforts. Because it’s a tightly integrated component of the Salesforce platform, you can quickly learn important concepts by using existing content.\n\n*   [Documentation Resources](./mc-resources-documentation.md)\n*   [Salesforce Platform Developer Tools](./mc-resources-tools.md)\n*   [Learning Resources for Marketing Cloud](./mc-resources-trailhead.md)\n*   [Marketing Cloud Next Video Library](./mc-resources-videos.md)"},{"id":"mc-security.md#0","file":"mc-security.md","relativePath":"mc-security.md","heading":"Security","body":"Data privacy and trusted access are important considerations in the development of a secure marketing platform. To help improve the security of your marketing data, follow these guidelines.\n\nDon’t share passwords or login information between multiple users, applications, or systems. If you work with integration partners, give each partner user a separate account. This step helps protect your customer data if a single account is compromised. It also makes it much easier to limit access and track actions that occur in your org.\n\nWhen you create user accounts or connected apps, follow the Principle of Least Privilege. The Principle of Least Privilege states that each user or other entity must have only the minimum level of permissions that are necessary to get the job done. Following this principle provides a layer of protection for your data against unauthorized access, faults, and malicious actions.\n\nThe Salesforce Platform provides several tools for monitoring the security of your org and data.\n\nTrack Login History\nTo view login data for the past 6 months, use the [Login History page](https://developer.salesforce.com/docs/atlas.en-us.securityImplGuide.meta/securityImplGuide/users_login_history.htm) in the Salesforce web app. The Login History page shows the HTTP login methods used, connected app logins, and more.\n\nTrack Changes to Object Fields\nYou can [track changes to fields in custom and standard objects](https://developer.salesforce.com/docs/atlas.en-us.securityImplGuide.meta/securityImplGuide/tracking_field_history.htm). Data is retained for at least 18 months, and it’s retained indefinitely when you enable Field Audit Trail.\n\nTrack Setup Changes\nIn orgs that have multiple admins, it can be helpful to see which user made a particular configuration change. To monitor configuration changes over the past 180 days, activate [Setup Audit Trail](https://developer.salesforce.com/docs/atlas.en-us.securityImplGuide.meta/securityImplGuide/admin_monitorsetup.htm) in your org.\n\nProtect your customer data and the availability of your org by testing in a sandbox. A sandbox org contains the same features and customer data as your production org. You can use a sandbox org for development, testing, and training, without worrying about compromising the data and applications in your production org.\n\nFor more information, see [Sandboxes: Staging Environments for Customizing and Testing](https://help.salesforce.com/s/articleView?id=platform.deploy_sandboxes_parent.htm)."}]}