SfSkills Domains Docs GitHub

Home / apex / mcae-pardot-api

mcae-pardot-api

Account Engagement (Pardot) REST API v5 from code — creating, reading and querying Prospects, Visitors, Visitor Activities and Form Handlers. Trigger keywords: Pardot API, Account Engagement API, prospect sync, visitor tracking API, form handler integration, MCAE REST API. NOT for connector setup, business unit provisioning or User Sync — use admin/mcae-pardot-setup. NOT for Marketing Cloud Engagement (Email Studio, Journey Builder) APIs — use apex/marketing-cloud-api.

Open the skill folder on GitHub

MCAE (Pardot) API v5

This skill activates when a practitioner or AI agent needs to integrate with the Account Engagement (Pardot) REST API v5 — covering authentication setup, Prospect CRUD, Visitor and Visitor Activity queries, Form Handler configuration, and cursor-based pagination. It does not cover Marketing Cloud Email Studio or Journey Builder APIs, nor does it cover Salesforce CRM object REST APIs.

Before Starting

Gather this context before working on anything in this domain:

Core Concepts

API v5 Authentication

API v5 uses the Salesforce OAuth 2.0 flow exclusively. You request a token from https://login.salesforce.com/services/oauth2/token (or the sandbox equivalent) using the Connected App's client_id and client_secret. The resulting access_token is sent as Authorization: Bearer {token}. Additionally, every request to pi.pardot.com must include the Pardot-Business-Unit-Id header. Missing either causes a 401. Tokens expire on the same schedule as Salesforce access tokens; implement token refresh using the refresh_token grant.

Prospects

Prospects are the core marketing entity in Account Engagement. Email address must be unique per business unit — duplicate email POST requests will upsert the existing record rather than create a new one (behavior is configurable). You can query Prospects by email (?fields=id,email&email=user@example.com), by Salesforce CRM ID (?crmLeadFQN=Lead/{sfId} or ?crmContactFQN=Contact/{sfId}), or by Pardot internal ID. CRUD is available: GET, POST (create), PATCH (update), DELETE. Field names in v5 use camelCase JSON, not underscores.

Visitors and Visitor Activities

Visitors represent anonymous tracking sessions identified by a tracking cookie set by the Pardot tracking pixel. A Visitor record is created automatically when an anonymous user loads a page with the pixel. Once the visitor submits a form or clicks a tracked email link, the Visitor is associated with a Prospect. Visitor Activity records capture every engagement event — email opens, email clicks, form submissions, page views, file downloads, custom redirects — and are queryable per visitor or prospect. Activity types are represented as integer codes in the type field (e.g., 1 = email click, 4 = form submission, 6 = page view).

Cursor-Based Pagination

API v5 does not support offset-based pagination. Instead, responses include a nextPageMark token in the response envelope when more pages exist. To retrieve the next page, include ?nextPageMark={value} in the subsequent request. The response also includes totalResults (total matching records) and nextPageUrl (convenience URL). Callers must follow nextPageMark iteratively; jumping to arbitrary offsets is not supported.

Common Patterns

Upsert Prospect by Email

When to use: You have a form submission or external system event and need to ensure the prospect exists and is up to date in MCAE.

How it works:

  1. POST to https://pi.pardot.com/api/v5/objects/prospects with JSON body containing email and any field values.
  2. If a prospect with that email already exists in the BU, MCAE updates the existing record (upsert behavior).
  3. Check the response id field to confirm which Prospect was created or updated.
  4. If you need to associate with a Salesforce Lead, include crmLeadFQN: "Lead/{sfLeadId}" in the body.

Why not the alternative: Querying first to check existence, then conditionally POSTing or PATCHing, is two round trips and introduces a race condition. The POST upsert pattern is atomic and recommended by Salesforce docs.

Paginated Visitor Activity Query

When to use: You need to export all engagement events for a prospect or date range, and the result set may exceed one page (default page size is 200, max is 200).

How it works:

  1. GET https://pi.pardot.com/api/v5/objects/visitor-activities?fields=id,type,createdAt,prospectId&prospectId={id}&orderBy=createdAt
  2. Check response body for nextPageMark.
  3. If present, issue next GET with ?nextPageMark={value} appended (keep all other filter params).
  4. Repeat until nextPageMark is absent from the response.
  5. Accumulate results across pages.

Form Handler POST

When to use: The company has an existing web form (on their own site, in a CMS, etc.) and wants submissions to create or update MCAE Prospects without migrating to a Pardot-hosted form.

How it works:

  1. In Account Engagement, create a Form Handler object and note its endpoint URL.
  2. The external form POSTs field values to the Form Handler URL using standard HTML form encoding (application/x-www-form-urlencoded).
  3. The Form Handler matches or creates a Prospect by email.
  4. Completion actions (e.g., add to list, assign to user, send autoresponder) execute as configured on the Form Handler.
  5. The Form Handler can be configured to redirect the browser to a success URL or return JSON for AJAX submissions.

Decision Guidance

SituationRecommended ApproachReason
Need to create or update a Prospect from backend codePOST to Prospects API v5 with JSON bodySupports all fields, returns full Prospect record, uses official API
External web form needs to submit into MCAEConfigure a Form Handler and POST form data to its endpointDesigned for this use case; handles completion actions; no API credentials required in browser
Need all engagement history for a given ProspectGET Visitor Activities filtered by prospectId with nextPageMark paginationVisitorActivity is the canonical engagement event store
Need to match a Pardot Prospect to a Salesforce LeadQuery Prospect by crmLeadFQN=Lead/{sfId}Avoids email-based ambiguity when multiple records exist
Authenticating from an external server-side systemUse Connected App OAuth Client Credentials flowAvoids embedding user credentials; tokens can be refreshed automatically
Need to identify which BU a request targetsInclude Pardot-Business-Unit-Id header on every requestRequired header; missing it returns 401 regardless of token validity

Step-by-step instructions for an AI agent or practitioner working on this task:

  1. Gather prerequisites — Collect the Connected App client_id/secret, the Pardot Business Unit ID, and the target object (Prospect, Visitor, VisitorActivity, or FormHandler). Confirm API v5 is being used, not a deprecated version.
  2. Obtain an OAuth access token — POST to https://login.salesforce.com/services/oauth2/token with grant_type, client_id, client_secret. Extract the access_token from the response. Store the refresh_token for automated renewal.
  3. Construct the request — Set base URL to https://pi.pardot.com/api/v5/objects/{object}. Add headers: Authorization: Bearer {token}, Pardot-Business-Unit-Id: {buId}, Content-Type: application/json. Add query params (fields, filters) or JSON body for mutations.
  4. Handle pagination — For list/query operations, inspect the response for nextPageMark. Loop until no nextPageMark is present. Do not use offset parameters.
  5. Validate the response — Check HTTP status code. 200/201 indicates success. 401 indicates missing or expired token or missing BU header. 400 indicates malformed request or field validation failure. Parse error details array for field-level messages.
  6. Test with a known record — Before wiring into production flows, use a known Prospect email to verify the round trip: GET by email, PATCH a safe field, GET again to confirm the change.
  7. Review checklist — Run through the Review Checklist below before marking the integration complete.

Review Checklist

Run through these before marking work in this area complete:

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

  1. Missing Pardot-Business-Unit-Id returns 401, not 400 — The error message does not say the header is missing; it looks identical to an invalid token error. Always verify this header is present before investigating token issues.
  2. Prospect POST upserts by email silently — Posting a new Prospect with an email that already exists in the BU does not return an error — it updates the existing Prospect. If you expected a new record, you will not detect the upsert from the status code alone; check whether the returned id matches an existing record.
  3. Visitor records are not directly queryable by email — Visitors are anonymous until conversion. You cannot query GET /visitors?email=.... To find visits for a known Prospect, query VisitorActivities by prospectId instead.
  4. Deprecated v3/v4 endpoints return XML by default — Callers migrating from older integrations may forget that v5 uses JSON (application/json) exclusively. v3/v4 used XML. Sending an Accept: application/xml header to v5 endpoints returns an error.

Output Artifacts

ArtifactDescription
Authenticated API request patternHeaders, base URL, and token acquisition flow
Prospect CRUD examplesCreate, read, update, delete operations with sample payloads
Visitor Activity queryPaginated fetch of all engagement events for a Prospect
Form Handler configuration guideSteps to create a Form Handler and wire an external form to it
Review checklistPre-completion verification checklist for API integrations

Dependencies

Package files