Guides

Integration contract

A stable, one-time integration pattern: your product keeps each user's current state synced to Meisa, and your growth team configures onboarding and lifecycle email entirely in the dashboard. This is the contract that lets engineering integrate once and never touch it again.

The contract in one sentence

Keep each user's current state synced to Meisa via POST /api/v1/contacts/upsert/, storing product-specific telemetry under custom_fields. Meisa detects changes and runs the automations your team has configured.

Required identifiers

  • email — the contact's primary email (the upsert key).
  • external_id — your internal user ID (stable, unique). Always send it.

Custom fields are the core

Put everything you want your team to automate on into custom_fields. Keep field names stable once introduced, and only send fields that matter to your lifecycle. Here's a copy/paste-friendly taxonomy — use what fits your domain:

Billing

  • plan·free / standard / pro / churned
  • subscription_status·active / trialing / past_due / canceled
  • billing_cycle·monthly / annual / lifetime

Lifecycle & onboarding

  • signup_date·ISO string
  • last_active·ISO string
  • onboarding_completed·boolean
  • signin_count·number

Usage / telemetry (examples)

  • posts_generated·number
  • ideas_generated·number
  • projects_created·number
  • feature_x_used·boolean

Acquisition & attribution

  • referral_source·string
  • utm_source·string
  • utm_campaign·string
  • country·string

Sync timing

  • On signup — sync immediately.
  • On plan / billing change — sync immediately.
  • On login — sync to refresh last_active and signin_count cheaply.
  • On milestones — sync when a threshold is crossed.

You don't need a nightly bulk re-sync. Event-driven deltas (signup, login, plan change, churn) keep Meisa accurate with minimal load.

How this enables non-technical workflows

Once state is flowing, your team builds automations against it without touching code:

  • Contact created → enroll in onboarding sequence.
  • Contact updated (e.g. plan free → pro) → tag and enroll.
  • Conditions on any custom field (e.g. posts_generated ≥ 5).

See How automations work for the full trigger and action set.

Minimal payload

upsert payload
{
  "email": "[email protected]",
  "external_id": "usr_12345",
  "first_name": "Jane",
  "custom_fields": {
    "plan": "free",
    "posts_generated": 0,
    "onboarding_completed": false
  }
}
PreviousHow automations workNextFull API reference