Quickstart - Zest Public API

The examples below use http://localhost:8080 as the API base URL for local development against the open-source reference implementation. Production base URLs (sandbox + live) are communicated during partner onboarding.

This walkthrough creates an SPV request end to end using the sandbox environment. By the end you will have:

Exchanged a partner JWT for an access token.
Listed available contract templates.
Submitted an SPV creation request with Idempotency-Key.
Verified the resulting spv_request.created webhook.

You need a sandbox client_id, the matching EdDSA private key, and a registered webhook URL + signing secret. Email sara@zestholdco.com to provision.

1. Mint a JWT assertion

Build a JWT with the following claims:

Claim	Value
`iss`	Your API base URL
`sub`	Your `client_id`
`aud`	`https://sandbox-api.zestequity.com`
`client_id`	Your `client_id`
`iat`	now (unix seconds)
`exp`	now + 60

Sign it with EdDSA using the private key registered with Zest.

New to JWT assertions? See Curity’s JWT-assertion walkthrough for an end-to-end primer on the grant type.

2. Exchange it for an access token

curl -X POST https://sandbox-api.zestequity.com/v1/oauth2/tokens \
  -H "Accept: application/json" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \
  -d "assertion=<JWT>"

Response:

{
  "accessToken": "eyJ...",
  "refreshToken": "eyJ...",
  "tokenType": "Bearer",
  "expiresIn": 3600,
  "refreshExpiresIn": 2592000
}

3. Submit an SPV request

Your templateId is assigned by Zest during partner onboarding. Use the value you were given for <your_template_id> below — see Contract templates for details.

curl -X POST https://sandbox-api.zestequity.com/v1/spv-requests \
  -H "Accept: application/json" \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "templateId": "<your_template_id>",
    "templateVersion": "1.0.0",
    "attributes": {
      "deal_name": "Acme Holdings Series A Syndicate",
      "deal_slug": "acme-series-a-2026",
      "company_id": "<your_company_id>",
      "deal_type": "<your_deal_type>",
      "security_type": "Equity",
      "currency": "USD",
      "price_per_share": {"currency": "USD", "value": "36.97"},
      "is_fixed_price": true,
      "minimum_ticket_size": {"currency": "USD", "value": "1000"},
      "start_date": "2026-06-01T00:00:00Z",
      "status_tag": "Live",
      "deal_stage": "executing",
      "investment_summary": "Subscription into Acme Holdings Series A shares.",
      "deal_documents_title": "Acme Series A Deck",
      "deal_documents_url": "https://example.com/acme-deck.pdf",
      "deal_documents_media_type": "pdf",
      "share_class_name": "Class A",
      "share_class_slug": "acme-class-a",
      "link_enabled": true,
      "private_code": "ACME01"
    }
  }'

Successful response (201 Created):

{
  "spvRequestSlug": "svr_a1b2c3",
  "status": "pending-review",
  "templateId": "<your_template_id>",
  "templateVersion": "1.0.0",
  "tenantSlug": "acme",
  "clientId": "client_xyz",
  "attributes": { "...": "..." },
  "createdAt": "2026-05-07T12:00:00Z",
  "updatedAt": "2026-05-07T12:00:00Z"
}

4. Same call in Python

import os
import uuid
import time
import jwt
import requests

CLIENT_ID = os.environ["ZEST_CLIENT_ID"]
PRIVATE_KEY = open(os.environ["ZEST_PRIVATE_KEY_PATH"]).read()
BASE_URL = "https://sandbox-api.zestequity.com"

now = int(time.time())
assertion = jwt.encode(
    {
        "iss": "https://your-api.example.com",
        "sub": CLIENT_ID,
        "aud": BASE_URL,
        "client_id": CLIENT_ID,
        "iat": now,
        "exp": now + 60,
    },
    PRIVATE_KEY,
    algorithm="EdDSA",
)

token = requests.post(
    f"{BASE_URL}/v1/oauth2/tokens",
    data={
        "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
        "assertion": assertion,
    },
).json()["accessToken"]

resp = requests.post(
    f"{BASE_URL}/v1/spv-requests",
    headers={
        "Authorization": f"Bearer {token}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "templateId": "<your_template_id>",
        "templateVersion": "1.0.0",
        "attributes": {
            "deal_name": "Acme Holdings Series A Syndicate",
            "deal_slug": "acme-series-a-2026",
            "company_id": "<your_company_id>",
            "deal_type": "<your_deal_type>",
            "security_type": "Equity",
            "currency": "USD",
            "price_per_share": {"currency": "USD", "value": "36.97"},
            "is_fixed_price": True,
            "minimum_ticket_size": {"currency": "USD", "value": "1000"},
            "start_date": "2026-06-01T00:00:00Z",
            "status_tag": "Live",
            "deal_stage": "executing",
            "investment_summary": "Subscription into Acme Holdings Series A shares.",
            "deal_documents_title": "Acme Series A Deck",
            "deal_documents_url": "https://example.com/acme-deck.pdf",
            "deal_documents_media_type": "pdf",
            "share_class_name": "Class A",
            "share_class_slug": "acme-class-a",
            "link_enabled": True,
            "private_code": "ACME01",
        },
    },
)
print(resp.status_code, resp.json())

5. Same call in Node.js

import { SignJWT, importPKCS8 } from "jose";
import { randomUUID } from "node:crypto";

const CLIENT_ID = process.env.ZEST_CLIENT_ID;
const PRIVATE_KEY_PEM = process.env.ZEST_PRIVATE_KEY;
const BASE_URL = "https://sandbox-api.zestequity.com";

async function run() {
  const privateKey = await importPKCS8(PRIVATE_KEY_PEM, "EdDSA");
  const now = Math.floor(Date.now() / 1000);

  const assertion = await new SignJWT({ client_id: CLIENT_ID })
    .setProtectedHeader({ alg: "EdDSA" })
    .setIssuer("https://your-api.example.com")
    .setSubject(CLIENT_ID)
    .setAudience(BASE_URL)
    .setIssuedAt(now)
    .setExpirationTime(now + 60)
    .sign(privateKey);

  const tokenRes = await fetch(`${BASE_URL}/v1/oauth2/tokens`, {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
      assertion,
    }),
  });
  const { accessToken } = await tokenRes.json();

  const res = await fetch(`${BASE_URL}/v1/spv-requests`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Idempotency-Key": randomUUID(),
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      templateId: "<your_template_id>",
      templateVersion: "1.0.0",
      attributes: {
        deal_name: "Acme Holdings Series A Syndicate",
        deal_slug: "acme-series-a-2026",
        company_id: "<your_company_id>",
        deal_type: "<your_deal_type>",
        security_type: "Equity",
        currency: "USD",
        price_per_share: { currency: "USD", value: "36.97" },
        is_fixed_price: true,
        minimum_ticket_size: { currency: "USD", value: "1000" },
        start_date: "2026-06-01T00:00:00Z",
        status_tag: "Live",
        deal_stage: "executing",
        investment_summary: "Subscription into Acme Holdings Series A shares.",
        deal_documents_title: "Acme Series A Deck",
        deal_documents_url: "https://example.com/acme-deck.pdf",
        deal_documents_media_type: "pdf",
        share_class_name: "Class A",
        share_class_slug: "acme-class-a",
        link_enabled: true,
        private_code: "ACME01",
      },
    }),
  });
  console.log(res.status, await res.json());
}

run();

6. Verify the webhook

You should receive a POST to your webhook URL with body:

{
  "eventId": "wde_...",
  "eventType": "spv_request.created",
  "occurredAt": "2026-05-07T12:00:00Z",
  "data": {
    "spvRequestSlug": "svr_a1b2c3",
    "templateId": "<your_template_id>",
    "templateVersion": "1.0.0",
    "tenantSlug": "acme",
    "attributes": { "...": "..." },
    "status": "pending-review"
  }
}

Verify the Zest-Signature header before processing — see Verification.

Next steps

Authentication — JWT-bearer details and common pitfalls.
SPV Requests — full lifecycle.
Webhooks Overview — event shape, ordering, dedup.

​1. Mint a JWT assertion

​2. Exchange it for an access token

​3. Submit an SPV request

​4. Same call in Python

​5. Same call in Node.js

​6. Verify the webhook

​Next steps

1. Mint a JWT assertion

2. Exchange it for an access token

3. Submit an SPV request

4. Same call in Python

5. Same call in Node.js

6. Verify the webhook

Next steps