SDK versus API

Where the Swapnice SDK and Partner API overlap, and where their capabilities differ.

Both surfaces talk to the same Partner API. The SDK is the supported way to integrate. The REST API is the stable contract underneath it.

The important difference is not “SDK can read profiles and the API cannot.” Both can. The SDK adds client-side collection, consent UX, retries, and typed helpers that a raw HTTP integration would otherwise have to build.

Quick comparison

Capability	TypeScript / Python SDK	Raw Partner API
OAuth 2.1 + PKCE token exchange	Built in	You implement
Connection session + consent UX	SDK presents or embeds the connect flow	You host redirects and poll session status
Automatic client-event capture	Yes, when you register observers	No. You must construct and POST every event
Device and session context enrichment	Added by the runtime SDK	You must attach context yourself
Offline queue and retry	Yes	You implement
Idempotency keys	Generated and retried for you	Required header on every mutating call
Typed requests and errors	Generated from the OpenAPI contract	You validate payloads
Server-to-server batch ingest	SDK events.batch helper	POST /v1/events/batch
Profile, claims, and intent reads	SDK read methods	GET /v1/profiles/:id and related routes
Webhook, app, and catalog admin	Thin SDK wrappers	Full HTTP surface
Consumer app Firebase APIs	Not available	Not available

If a teammate heard that “the SDK has more functionality,” this is what that means: the SDK can observe in-app behavior, run the Swapnice connection and consent flow, and keep events ordered through retries. The API can accept the same events and return the same profiles, but it will not collect or consent for you.

Use the SDK when

• You are embedding Swapnice in a mobile app, web app, or checkout surface
• You want Swapnice to collect consented first-party events as users move through your product
• You need the hosted connection and consent experience rather than a custom OAuth UI
• You want typed clients, automatic idempotency, and token refresh

Install the generated client:

npm install swapnice-sdk-ts

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

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

The same OpenAPI contract also generates a Python client for backend jobs.

Use the API directly when

• A partner backend or ETL job is the only writer
• You already collected consent in your own UI and only need to POST receipts and events
• You are registering webhook endpoints, managing apps, or rebuilding ontologies
• You are debugging with cURL, Postman, or an API gateway

Every SDK method maps to a documented HTTP route in the API reference. Replays and server jobs can call those routes without the client SDK.

What neither surface does

Neither the SDK nor the Partner API exposes Swapnice consumer-app internals:

• Wallet, Dwolla, or Plaid credentials
• NFC pack activation internals
• Private account fields from the consumer user record
• Another partner’s raw events or unresolved identities

Installing the SDK does not expand the purposes a user granted. Events collected for personalization stay unavailable for another purpose until that purpose is granted.

Capability split in practice

The usual split is:

1. Client SDK in the consumer-facing app to connect, collect consent, and observe product interactions.
2. Partner backend + API or server SDK to upsert customers, register webhooks, and read profiles and intents for the partner product.

See integration for the combined implementation path.