Skip to main content
This page walks the canonical happy path for a partner integration. Use it as a checklist when designing your integration’s state machine.

​
High-level sequence

​
Where the partner waits

Two synchronous gates can take significant wall-clock time:
  1. SPV approval. Between spv_request.created and spv_request.completed there is human review. Plan your UI to surface “pending review” to your operator and rely on the webhook to advance the flow.
  2. Subscription completion. Between funding_receipt.uploaded and subscription.completed Zest reconciles the wire. This is also human-paced.
In both cases, persist your local state machine and react to the corresponding webhook. Don’t poll — every webhook delivery uses the retry schedule and dedup recipe.

​
Where uploads block each other

Within a single subscription:
  • Both endpoints accept files up to 10 MB and only PDF / JPEG / PNG / WEBP.

​
Failure handling cheatsheet

​
Suggested data model on the partner side

For each Zest resource you should store, at minimum:
  • spv_request.{slug, status, materialisedRefs} keyed by your local intent id.
  • investors.{partnerInvestorId, zestPersonId} mapping table.
  • subscriptions.{subscriptionSlug, partnerSubscriptionId, personId, spvSlug, status} per investor + SPV.
  • webhook_events.{eventId, eventType, occurredAt} for dedup + audit.