Integration and sample code

Implementation requirements and end-to-end examples for the Swapnice SDK and Partner API.

This page is the implementation path for a V1 partner integration: register an app, complete OAuth, create a customer, collect consent, send events, and read a profile.

Requirements

Partner application

A confidential backend that can store client_id and client_secret. Public/browser clients can start connection sessions but must not hold the client secret.

Exact redirect URIs

Every redirect_uri must match a registered URI exactly. Wildcards are not accepted in production.

OAuth 2.1 with PKCE

Authorization-code flow only. code_challenge_method must be S256. Access tokens are short-lived (about 15 minutes). Refresh tokens rotate when offline_access is granted.

Consent before events

POST /v1/events is rejected without a valid consent receipt for the event’s consent_purpose.

Idempotency

Send an Idempotency-Key header on mutating calls. Replays return the original result. A reused key with a different body returns 409 idempotency_conflict.

Scopes

Request only the scopes you will call. A typical profile-reading integration uses connections:write, consent:write, events:write, profile:read, claims:read, and intents:read.

Recommended scope templates

Template	Scopes	Use
Ingest only	consent:write events:write	Send consented events
Connect and ingest	connections:write connections:read consent:write consent:read events:write events:read	Full SDK connect flow
Profile reads	previous + profile:read claims:read intents:read	Read resolved intelligence
Full partner	previous + customers:write customers:read webhooks:write webhooks:read	Production integration

1. Configure the client

TypeScript

import { SwapniceClient } from "swapnice-sdk-ts";

const swapnice = new SwapniceClient({
  environment: process.env.SWAPNICE_ENV === "production" ? "production" : "sandbox",
  clientId: process.env.SWAPNICE_CLIENT_ID!,
  clientSecret: process.env.SWAPNICE_CLIENT_SECRET!,
  redirectUri: process.env.SWAPNICE_REDIRECT_URI!,
});

2. Create or upsert the partner customer

The customer is your user. You do not need their global Swapnice user id.

TypeScript

const { customer } = await swapnice.customers.upsert({
  external_id: "partner_user_1842",
  profile: { username: "collector1842" },
  metadata: { loyalty_tier: "gold", source: "ios" },
});

Example response:

{
  "status": "created",
  "customer": {
    "id": "cust_8f2a1c",
    "app_id": "app_91b0",
    "external_id": "partner_user_1842",
    "status": "active",
    "profile": { "username": "collector1842" },
    "metadata": { "loyalty_tier": "gold", "source": "ios" },
    "created_at": "2026-08-26T16:01:00.000Z",
    "updated_at": "2026-08-26T16:01:00.000Z"
  }
}

Customer profile accepts public display fields only (username, bio_markdown, avatar_url, banner_url, coarse public location). Do not send payment, government-id, or credential data.

3. Start a connection session

This is the Plaid-Link-style step: your app opens a Swapnice-hosted connection URL so the user can authorize the link.

TypeScript

const session = await swapnice.connectionSessions.create({
  customer_id: customer.id,
  requested_purposes: ["personalization", "analytics"],
  redirect_uri: process.env.SWAPNICE_REDIRECT_URI!,
});

// Open session.connection_url in-app or in the system browser.

{
  "session_id": "cs_0b77e2",
  "client_token": "cst_...",
  "connection_url": "https://api.sandbox.swapnice.com/connect/cs_0b77e2",
  "status": "created",
  "expires_at": "2026-08-26T16:06:00.000Z"
}

Poll GET /v1/connection-sessions/:session_id until status is authorized or completed.

4. Record the consent receipt

After the user accepts, persist the receipt. Events for a purpose are rejected until this exists.

TypeScript

const consent = await swapnice.consentReceipts.create({
  customer_id: customer.id,
  connection_session_id: session.session_id,
  purposes: ["personalization", "analytics"],
  terms_version: "2026-08-01",
  privacy_policy_version: "2026-08-01",
});

{
  "receipt_id": "cr_44aa01",
  "customer_id": "cust_8f2a1c",
  "purposes": ["personalization", "analytics"],
  "status": "granted",
  "granted_at": "2026-08-26T16:02:12.000Z"
}

5. Ingest a consented event

The SDK can emit this from an observer. A backend can POST the same payload. Either way, include consent_purpose and an Idempotency-Key.

TypeScript

const accepted = await swapnice.events.create(
  {
    customer_id: customer.id,
    client_event_id: "evt_checkout_8891",
    consent_receipt_id: consent.receipt_id,
    consent_purpose: "personalization",
    event_type: "purchase.completed",
    ontology: "intent",
    ontology_category: "outcome",
    object: "sku_blue_eyes_tin",
    occurred_at: new Date().toISOString(),
    payload: { sku: "sku_blue_eyes_tin", currency: "USD", amount: 24.99 },
    context: { surface: "checkout", storefront: "ios" },
    confidence: 1,
    provenance: {
      source_partner: "partner_app",
      source_system: "ios",
      collected_at: new Date().toISOString(),
    },
  },
  { headers: { "Idempotency-Key": "evt_checkout_8891" } },
);

202 response. The event is accepted and queued; heavier projection is asynchronous.

{
  "event_id": "evt_9c21",
  "status": "accepted",
  "sequence": 7,
  "accepted_at": "2026-08-26T16:04:00.120Z",
  "processing_status": "queued"
}

Batch the same shape to POST /v1/events/batch (1–100 events).

6. Read the resolved profile and intents

Reads are synchronous and scoped to the caller plus optional consent_purpose.

TypeScript

const profile = await swapnice.profiles.get("cust_8f2a1c", {
  consent_purpose: "personalization",
});

const intents = await swapnice.profiles.intents("cust_8f2a1c", {
  consent_purpose: "personalization",
  category: "outcome",
});

Sample profile and intent bodies are on outputs.

7. Register a webhook endpoint

const { endpoint, signing_secret } = await swapnice.webhookEndpoints.create({
  url: "https://partner.example.com/swapnice/webhooks",
  enabled_events: ["event.processed", "event.failed", "consent.revoked", "profile.updated"],
});

Delivery of those events is near-term. Registration and secret issuance are live so you can build the receiver during the pilot.

OAuth token exchange

If you are not using the SDK auth helper, the raw PKCE exchange is:

# 1. Authorization code
curl -X POST "$SWAPNICE_API_BASE_URL/oauth/authorize" \
  -H "Content-Type: application/json" \
  -d '{
    "response_type": "code",
    "client_id": "'"$SWAPNICE_CLIENT_ID"'",
    "redirect_uri": "'"$SWAPNICE_REDIRECT_URI"'",
    "code_challenge": "'"$CODE_CHALLENGE"'",
    "code_challenge_method": "S256",
    "customer_id": "cust_8f2a1c",
    "scope": "connections:write consent:write events:write profile:read claims:read intents:read"
  }'

# 2. Token
curl -X POST "$SWAPNICE_API_BASE_URL/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "client_id": "'"$SWAPNICE_CLIENT_ID"'",
    "client_secret": "'"$SWAPNICE_CLIENT_SECRET"'",
    "code": "'"$AUTH_CODE"'",
    "code_verifier": "'"$CODE_VERIFIER"'",
    "redirect_uri": "'"$SWAPNICE_REDIRECT_URI"'"
  }'

Discovery lives at GET /.well-known/oauth-authorization-server.

Error shape

All Partner API errors use a stable machine-readable code and a request id. They never include secrets or private wallet data.

{
  "error": {
    "code": "consent_required",
    "message": "A valid consent receipt is required for this event purpose.",
    "request_id": "req_3e19c0"
  }
}

Common codes: idempotency_key_required, idempotency_conflict, consent_required, invalid_scope, invalid_redirect_uri.

Next

• Authentication — PKCE, scopes, and token errors
• Consent and account linking
• Events and intent ontology
• Request walkthrough
• What data is collected
• API reference