Technical Specification: Website Registration → SFMC Integration

Executive Summary

When a user fills out and submits the registration form on the website, their information (name, email, opt-in status, timestamp, etc.) is sent to Salesforce Marketing Cloud (SFMC) and stored in a Data Extension — essentially a table within SFMC that holds subscriber data.

Once the data is in SFMC, the marketing team can:

Build audiences and segments by filtering on any captured field (e.g., all users who opted in, all users from a specific source page)
Trigger Journey Builder campaigns — either immediately upon registration (e.g., a welcome email or double opt-in confirmation) or on a scheduled/batch basis (e.g., a daily newsletter send)
Track and report on registrations over time using the stored data

The development team will handle the technical API integration on the website backend. The SFMC Admin will need to set up the Data Extension and provide API credentials. No SFMC credentials will be exposed on the website itself — all communication happens server-to-server.

What's needed from the marketing team:

Confirm the list of fields to capture on the registration form (see Section 2.2 for the proposed list)
Decide whether the welcome/confirmation email should send immediately or as a scheduled batch (see Section 5.4)
Confirm whether double opt-in (email verification) is required
Confirm the consent/compliance requirements (GDPR, CAN-SPAM, CASL) that may affect what fields are captured and how consent is recorded

What's needed from the SFMC Admin:

Create an Installed Package with API credentials (Section 2.1)
Create the target Data Extension with the agreed-upon fields (Section 2.2)
Configure the Journey Builder API Event entry source if real-time triggers are needed (Section 2.3)

Purpose

This document defines the technical requirements for integrating a website registration form with Salesforce Marketing Cloud (SFMC) via the REST API. The integration will create/update subscriber records in a Data Extension (DE) and optionally trigger Journey Builder campaigns in real time.

1. Architecture Overview

plaintext

[Website Form] → [Web Backend] → [SFMC REST API] → [Data Extension] → [Journey Builder]
                      │
                      ├── 1. Request OAuth2 token (cached, refreshed on expiry)
                      ├── 2. POST registration payload to SFMC
                      └── 3. SFMC upserts DE row → Journey triggers (real-time or batch)

Key design decisions:

The website backend (not the browser) handles all SFMC API calls to protect credentials and avoid CORS issues.
The OAuth2 access token must be cached server-side and refreshed only upon expiration (tokens expire every ~20 minutes).
The web backend should not block the user's form submission on the SFMC API response. If SFMC is slow or unavailable, the registration should still succeed locally and the SFMC payload should be queued/retried asynchronously.

2. SFMC Admin Prerequisites

Before development begins, the SFMC Administrator must complete the following:

2.1 Create an Installed Package (API Integration)

Navigate to Setup → Apps → Installed Packages
Create a new Installed Package
Add a component: API Integration (Server-to-Server)
Assign the following scopes:

Scope	Required For
`Data Extensions (Read and Write)`	Upserting registration records into the DE
`Journeys (Read)`	Reading journey definitions (if needed)
`List and Subscribers (Read and Write)`	Managing subscriber status
`Interactions (Execute)`	Triggering Journey Builder events (Path B only)

Deliverables to Dev team:

Client ID
Client Secret
Tenant-Specific Subdomain (TSD), e.g., https://[subdomain].auth.marketingcloudapis.com
Account ID (MID)

2.2 Create the Target Data Extension

Create a Data Extension in SFMC (e.g., Web_Registrations)
Mark it as Sendable (required for email sends via Journey Builder)
Configure the following fields:

Field Name	SFMC Data Type	Primary Key?	Nullable?	Notes
`SubscriberKey`	Text (254)	Yes	No	Unique identifier. Use email address or a generated UUID. Must be unique per contact.
`EmailAddress`	EmailAddress	No	No	User's email address. Must be valid email format.
`FirstName`	Text (100)	No	Yes	User's first name
`LastName`	Text (100)	No	Yes	User's last name
`OptInStatus`	Boolean	No	No	`true` if user opted in to marketing communications, `false` otherwise. Default: `false`
`RegistrationTimestamp`	Date	No	No	ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ` (UTC)
`Source`	Text (50)	No	Yes	Hardcoded: `Website Registration`
`IPAddress`	Text (45)	No	Yes	User's IP address for compliance/audit
`UserAgent`	Text (255)	No	Yes	Browser user agent string
`PageURL`	Text (500)	No	Yes	URL of the page where the form was submitted

Configure Send Relationship: Map SubscriberKey → _SubscriberKey and EmailAddress → Email Address

Deliverable to Dev team:

External Key of the DE (e.g., Web_Registrations_2026)

2.3 Configure Journey Builder Entry Source (Path B only — real-time)

If the journey should trigger immediately upon registration:

Create or open the target Journey in Journey Builder
Add an API Event entry source
Configure the event to use the Data Extension created in step 2.2
Map the incoming data fields

Deliverable to Dev team:

EventDefinitionKey (generated by SFMC when the API Event is configured, e.g., APIEvent-xxxx-xxxx-xxxx-xxxx)

3. Authentication (OAuth 2.0 Server-to-Server)

SFMC uses OAuth 2.0 with the client_credentials grant type. The access token must be included as a Bearer token in all subsequent API calls.

3.1 Token Request

http

POST https://[YOUR_SUBDOMAIN].auth.marketingcloudapis.com/v2/token
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "account_id": "YOUR_MID"
}

3.2 Token Response

json

{
  "access_token": "eyJhbGciOiJSUzI1NiIsIn...",
  "token_type": "Bearer",
  "expires_in": 1199,
  "rest_instance_url": "https://[YOUR_SUBDOMAIN].rest.marketingcloudapis.com/"
}

3.3 Token Caching Strategy

Store the access_token and its expiration time in server-side memory (e.g., Redis, in-memory cache, or a singleton).
Calculate expiry as: token_acquired_at + expires_in (minus a 60-second safety buffer).
On each API call, check if the token is still valid. If expired or about to expire, request a new token before proceeding.
Do not request a new token on every API call — SFMC enforces rate limits on token requests.

4. Data Ingestion: Upsert to Data Extension

4.1 Endpoint (Synchronous)

This is the recommended endpoint for single-record upserts from a registration form. It uses the DE's External Key and the primary key field value to perform an upsert (insert if new, update if exists).

http

POST https://[YOUR_SUBDOMAIN].rest.marketingcloudapis.com/hub/v1/dataevents/key:[DE_EXTERNAL_KEY]/rowset
Authorization: Bearer [ACCESS_TOKEN]
Content-Type: application/json

4.2 Request Payload

The payload uses a keys object for the primary key field(s) and a values object for all other fields. If a record with the matching key already exists, the values fields are updated. If not, a new row is inserted.

json

[
  {
    "keys": {
      "SubscriberKey": "user@example.com"
    },
    "values": {
      "EmailAddress": "user@example.com",
      "FirstName": "Jane",
      "LastName": "Doe",
      "OptInStatus": true,
      "RegistrationTimestamp": "2026-06-23T14:52:45Z",
      "Source": "Website Registration",
      "IPAddress": "192.168.1.1",
      "UserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
      "PageURL": "https://example.com/register"
    }
  }
]

4.3 Response

Success (200 OK):

json

{
  "results": [
    {
      "rows": 1,
      "errorcode": 0,
      "status": "OK"
    }
  ]
}

Validation Error (400 Bad Request):

json

{
  "results": [
    {
      "rows": 0,
      "errorcode": 1,
      "status": "Error",
      "message": "Unable to save rows for data extension..."
    }
  ]
}

4.4 Alternative: Asynchronous Upsert (High Traffic)

If the registration form receives high traffic or if the backend needs to decouple from SFMC response times, use the async endpoint instead:

http

POST https://[YOUR_SUBDOMAIN].rest.marketingcloudapis.com/data/v1/async/dataextensions/key:[DE_EXTERNAL_KEY]/rows
Authorization: Bearer [ACCESS_TOKEN]
Content-Type: application/json

Payload format differs slightly (flat object, no keys/values split):

json

{
  "items": [
    {
      "SubscriberKey": "user@example.com",
      "EmailAddress": "user@example.com",
      "FirstName": "Jane",
      "LastName": "Doe",
      "OptInStatus": true,
      "RegistrationTimestamp": "2026-06-23T14:52:45Z",
      "Source": "Website Registration"
    }
  ]
}

Note: The async endpoint returns a requestId that can be used to check the status of the operation. It does not guarantee immediate upsert — the data is queued and processed by SFMC. Use this only if you don't need synchronous confirmation.

5. Journey Builder Trigger (Real-Time Option)

If the journey should fire immediately upon registration (e.g., instant welcome email, double opt-in confirmation), use the Journey Builder Event API instead of (or in addition to) the DE upsert. This endpoint injects the contact into the journey and writes the data to the journey's backing DE in a single call.

5.1 Endpoint

http

POST https://[YOUR_SUBDOMAIN].rest.marketingcloudapis.com/interaction/v1/events
Authorization: Bearer [ACCESS_TOKEN]
Content-Type: application/json

5.2 Request Payload

json

{
  "ContactKey": "user@example.com",
  "EventDefinitionKey": "APIEvent-xxxx-xxxx-xxxx-xxxx",
  "EstablishContactKey": true,
  "Data": {
    "EmailAddress": "user@example.com",
    "FirstName": "Jane",
    "LastName": "Doe",
    "OptInStatus": true,
    "RegistrationTimestamp": "2026-06-23T14:52:45Z",
    "Source": "Website Registration"
  }
}

Field descriptions:

ContactKey — The unique identifier for the contact in SFMC. Typically the same as SubscriberKey.
EventDefinitionKey — Provided by the SFMC Admin when configuring the API Event entry source.
EstablishContactKey — Set to true to create the contact record if it doesn't already exist.
Data — Key/value pairs matching the fields configured in the API Event entry source.

5.3 Response

Success (201 Created):

json

{
  "eventInstanceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

5.4 Path A vs Path B Decision Guide

Criteria	Path A (DE Upsert Only)	Path B (Journey Event API)
Real-time journey trigger	No — requires batch automation	Yes — fires immediately
Data stored in DE	Yes	Yes (journey's backing DE)
Use case	Audience building, segmentation, scheduled sends	Welcome emails, double opt-in, transactional sends
API calls per registration	1 (auth + upsert)	1 (auth + event)
Complexity	Lower	Slightly higher (requires SFMC Admin to configure API Event)
Recommended for	Newsletter signups, lead capture	Immediate confirmation/welcome flows

Recommendation: If you need an immediate welcome email or double opt-in confirmation, use Path B. If you just need to collect data for audience building and scheduled campaigns, use Path A. You can also use both — upsert to a primary DE for record-keeping (Path A) and fire the journey event (Path B) for the immediate send.

6. Error Handling Requirements

The Dev team must implement handling for the following HTTP response codes:

HTTP Status	Meaning	Required Action
`200` / `201`	Success	Log success, continue
`400`	Bad Request — payload schema mismatch, missing required field, or invalid data type	Log the full request payload and response body. Do not retry — fix the payload.
`401`	Unauthorized — token expired or invalid	Refresh the OAuth2 token and retry the request once. If the retry also returns 401, alert the team (credentials may be invalid).
`403`	Forbidden — insufficient scopes or IP not allowlisted	Check Installed Package scopes. SFMC may require IP allowlisting for API access.
`409`	Conflict — duplicate primary key (sync endpoint)	Typically handled by the upsert logic. If using insert-only, treat as a duplicate and skip.
`429`	Too Many Requests — rate limit exceeded	Implement exponential backoff retry (e.g., 1s, 2s, 4s, 8s). Log and alert if retries are exhausted.
`500` / `502` / `503`	SFMC server error	Retry with exponential backoff (up to 3 attempts). If all retries fail, queue the payload for later processing.

6.1 Retry & Queue Strategy

Implement a dead-letter queue (DLQ) or persistent queue for payloads that fail after all retry attempts.
Failed payloads should be retried by a background worker (e.g., cron job or queue processor) at regular intervals.
Include a retry_count and last_attempt_at field in the queue to prevent infinite retries.

7. Security Requirements

Never expose SFMC credentials (client_id, client_secret) in client-side code. All API calls must originate from the web backend.
Store credentials in environment variables or a secrets manager (e.g., AWS Secrets Manager, Vault). Never commit to version control.
Validate and sanitize all form input on the server before constructing the SFMC payload:
- Email: RFC 5322 validation
- Names: Strip HTML/scripts, enforce max length
- Boolean fields: Coerce to strict true/false
- Timestamp: Generate server-side in UTC, do not trust client-provided timestamps
Implement rate limiting on the registration form endpoint to prevent abuse.
Log all SFMC API interactions (request, response, status code, timestamp) for audit and debugging. Do not log the OAuth2 access_token or client_secret.

8. Data Flow Summary

plaintext

1. User submits registration form on website
2. Web backend validates input (email format, required fields, sanitization)
3. Web backend checks cached OAuth2 token:
   a. If valid → use cached token
   b. If expired → request new token from SFMC auth endpoint
4. Web backend constructs JSON payload with registration data
5. Web backend sends POST to SFMC REST API:
   a. Path A: /hub/v1/dataevents/key:[DE_KEY]/rowset (DE upsert)
   b. Path B: /interaction/v1/events (Journey trigger)
6. SFMC processes the request:
   a. Path A: Upserts row in Data Extension
   b. Path B: Injects contact into Journey + writes to backing DE
7. Web backend handles response:
   a. Success → log and return success to user
   b. Error → retry (401/429/5xx) or queue for later (400/persistent failures)
8. SFMC Admin uses DE data for:
   a. Audience segmentation and filtering
   b. Journey Builder entry sources (batch automations)
   c. Email send definitions

9. Open Questions for Stakeholders

Journey timing: Should the welcome/confirmation email send immediately (Path B) or is a batch/scheduled send acceptable (Path A)?
Subscriber Key strategy: Will EmailAddress serve as the SubscriberKey, or will you use a generated UUID/internal user ID? This must be consistent across all SFMC integrations.
Double opt-in: Does the registration require email verification (double opt-in) before the contact is considered active? If so, the journey should include a verification email step.
Additional fields: Are there any fields beyond what's listed in the DE schema (Section 2.2) that need to be captured (e.g., phone number, company name, country, marketing preferences)?
Existing contacts: How should the integration handle a user who already exists in SFMC with a different email? Should it update, skip, or create a duplicate?
Compliance: Are there GDPR/CAN-SPAM/CASL requirements for consent capture and timestamp logging that need additional fields or workflows?