1272: wire up form to pardot - explore account engagement api

[DNR500]

issue: 1272

Explore Account Engagement API for Subscription

Overview

This PR explores using the Account Engagement API (Pardot) for handling subscriptions via editor-api.

To run this locally, you may need to enable caching:

docker compose run --rm api rails dev:cache
docker compose restart api

This is an exploration to validate the approach. To make this production-ready, we would still need to consider:

• Rate limiting
• Monitoring / logging
• Additional tests
• Environment-specific configuration

---

Key Differences vs Form Handler

• Different data flow in Pardot
  This approach updates prospects directly via the API. The data may not appear in the same place as Form Handler submissions.

• Reporting considerations
  API-driven updates may not show up in “Form Handler submissions” views. We need to confirm where this data lives and that marketing can still use it effectively.

• Server-to-server integration
  Everything stays backend-driven, using a cleaner and more controlled integration pattern.

• Cleaner success/failure handling
  API responses are easier to interpret compared to Form Handler redirects.

---

How to Test (Postman)

Request

• Method: POST
• URL: http://localhost:3009/api/subscriptions

Headers:

• Content-Type: application/json
• Accept: application/json

Body (raw JSON):

{
  "subscription": {
    "email": "teacher@example.com",
    "test_opt_in": true,
    "privacy_policy": true
  }
}

Expected Responses

• 200 OK → valid request, provider accepted
• 422 Unprocessable Content → validation error
• 503 Service Unavailable → provider unavailable / not configured
• 502 Bad Gateway → provider response rejected or unclear

Invalid Example

{
  "subscription": {
    "email": "bad-email",
    "test_opt_in": true,
    "privacy_policy": false
  }
}

---

Pardot Setup

API-Based Subscription Integration

This integration ensures subscription data is captured in a usable format within Pardot.
The workflow should be confirmed with the marketing team before implementation.

---

1. Payload Contract

The editor-api expects:

• email (required)
• test_opt_in (boolean)
• privacy_policy (boolean — must be true)

---

2. Pardot Admin — Setup & Provide

A) Fields

Confirm these fields exist and are API-writable:

• email (standard Prospect field)
• test_opt_in (custom field — API name must be exactly test_opt_in)
• privacy_policy (custom field — API name must be exactly privacy_policy)

Also share any validation rules or defaults that could block writes.

---

B) Newsletter List

Provide:

• List name(s)
• List ID(s) / API identifiers
• Expected behaviour (e.g. add on signup, idempotent if already a member)

---

C) Auth & Config (Required per environment)

Provide for test/POC:

• PARDOT_AUTH_URL
• PARDOT_CLIENT_ID
• PARDOT_CLIENT_SECRET (securely)
• PARDOT_AUTH_SCOPE (if required)
• PARDOT_API_SUBSCRIPTION_URL
• PARDOT_BUSINESS_UNIT_ID

---

D) Permissions

Confirm the integration user can:

• Create/update prospects
• Write to email, test_opt_in, privacy_policy
• Update newsletter list membership

---

E) Setup Confirmation

Confirm:

• Fields exist with exact API names
• Newsletter list exists and is API-accessible
• Business unit and endpoints are correct per environment

---

3. Developer — Implementation

A) Environment Config

• Wire all provided values for the test environment

---

B) Field & List Mapping

• Ensure backend mapping matches Pardot fields and list exactly

---

C) Auth Verification

• Confirm OAuth token can be retrieved
• Confirm API calls succeed

---

D) End-to-End Success Case

Submit a valid request and verify in Pardot:

• Prospect created/updated
• test_opt_in saved correctly
• privacy_policy saved correctly
• List membership applied

---

E) Failure Cases

• Confirm endpoint handles invalid payloads and API failures cleanly

---

TODO

Define environment setup:

• Local / Dev
• Staging / Test
• Production

[github-actions]

Test coverage

89.02% line coverage reported by SimpleCov.
Run: https://github.com/RaspberryPiFoundation/editor-api/actions/runs/25109303457