How to Integrate Ortto with Your Headless CMS

What is Ortto?

Ortto is a customer data and marketing automation platform used to collect customer profiles, track behavioral events, build segments, and send email, SMS, in-app, and ad audience campaigns. Marketing, growth, SaaS, and ecommerce teams use Ortto when they need a customer data platform and journey builder in one place. Its core strength is connecting profile data with activity data so teams can trigger campaigns from real customer behavior.

Why integrate Ortto with a headless CMS?

Ortto works best when it gets clean context, not just an email address. If someone downloads a pricing guide, registers for a webinar, or signs up from a localized landing page, your marketing team needs to know the asset, campaign, topic, language, consent state, and source URL. Without an integration, that context usually lives in hidden form fields, spreadsheet imports, or one-off Zapier-style mappings that break when a field name changes.

Architecture overview

A typical Sanity and Ortto integration starts with structured content in the Content Lake. For example, a newsletterSignup document references a campaign document and a gatedAsset document. A Sanity webhook fires when that signup is created, or when a campaign page is published. The webhook calls a server endpoint or Sanity Function with the changed document ID. That server-side code uses @sanity/client and GROQ to fetch exactly the fields Ortto needs, such as email, first name, consent state, campaign code, asset title, locale, persona, and source URL. The handler then calls Ortto's REST API, usually POST https://api.ap3api.com/v1/person/merge with the X-Api-Key header, to create or update the person record. If you've defined custom activities in Ortto, the same handler can send a conversion event to Ortto after the person is merged. From there, Ortto can add the person to segments, trigger email or SMS journeys, sync ad audiences, and show the activity in the person timeline.

Common use cases

Step-by-step integration

1. 1

   Set up Ortto access

   Create or sign in to your Ortto account, then create a private API key in Ortto settings. Give it access to people and activities if you plan to merge profiles and record content conversions. In Ortto, create any custom fields you need, such as campaign code, source asset, persona, or journey stage, and copy their field IDs.

2. 2

   Model marketing data in Sanity Studio

   Create schemas for campaign, gatedAsset, landingPage, and newsletterSignup. Include fields such as title, slug, campaignCode, persona, journeyStage, locale, consentText, orttoFieldValue, and references between signups and the content that caused them.

3. 3

   Create a Sanity webhook

   Add a webhook that fires on create or publish events. For lead capture, use a filter like _type == 'newsletterSignup' && optIn == true. For campaign metadata sync, use a filter like _type in ['campaign', 'gatedAsset'] and only trigger on published documents.

4. 4

   Fetch the full document with GROQ

   In a Sanity Function, webhook listener, or middleware route, use @sanity/client to fetch the changed document. Use GROQ projections to join referenced campaign and asset data so Ortto receives one clean payload instead of partial IDs.

5. 5

   Send the mapped data to Ortto

   Call Ortto's REST API from server-side code. Use POST /v1/person/merge to create or update people by email, map Sanity fields to Ortto system and custom field IDs, and only send people who have valid consent.

6. 6

   Test the end-to-end path

   Create a test signup in Sanity Studio, confirm the webhook ran, check your server logs, and verify the person in Ortto under People. Then submit the real frontend form and confirm that the Ortto profile contains the expected campaign and content fields.

Code example

import {createClient} from '@sanity/client'
import {NextRequest, NextResponse} from 'next/server'

const sanity = createClient({
  projectId: process.env.SANITY_PROJECT_ID!,
  dataset: process.env.SANITY_DATASET!,
  apiVersion: '2025-02-19',
  token: process.env.SANITY_READ_TOKEN,
  useCdn: false,
})

const query = `*[_id == $id][0]{
  email, firstName, lastName, optIn,
  "assetTitle": sourceAsset->title,
  "campaignCode": campaign->campaignCode,
  "persona": campaign->persona
}`

export async function POST(req: NextRequest) {
  const body = await req.json()
  const id = body._id || body.ids?.created?.[0] || body.ids?.updated?.[0]
  if (!id) return NextResponse.json({skipped: 'No document id'}, {status: 202})

  const lead = await sanity.fetch(query, {id})
  if (!lead?.optIn || !lead.email) {
    return NextResponse.json({skipped: 'No consent or email'}, {status: 202})
  }

  const orttoRes = await fetch('https://api.ap3api.com/v1/person/merge', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Api-Key': process.env.ORTTO_API_KEY!,
    },
    body: JSON.stringify({
      people: [{
        fields: {
          'str::email': lead.email,
          'str::first': lead.firstName,
          'str::last': lead.lastName,
          'str:cm:source-asset': lead.assetTitle,
          'str:cm:campaign-code': lead.campaignCode,
          'str:cm:persona': lead.persona,
        },
      }],
      merge_by: ['str::email'],
    }),
  })

  if (!orttoRes.ok) {
    return NextResponse.json({error: await orttoRes.text()}, {status: 502})
  }

  return NextResponse.json({synced: true})
}

How Sanity + Ortto works

CMS approaches to Ortto

Keep building

Explore related integrations to complete your content stack.