Request walkthrough

Ordered sandbox calls from OAuth through profile read, including the payloads and fields that usually trip teams up.

This is the happy path a partner engineer should complete in sandbox before the technical session. Use the TypeScript SDK or raw HTTP. Postman works if you do not use its built-in OAuth 2.0 helper.

Base URL: https://api.sandbox.swapnice.com (or a Swapnice-issued sandbox host).

All /v1/* calls after token exchange need Authorization: Bearer $ACCESS_TOKEN. Mutating calls also need Idempotency-Key. Access tokens last about 15 minutes.

Field-name cheat sheet

Call	ID in the body
POST /v1/customers	external_id — not customer_id
Connection, consent, events, profiles	customer_id (the id Swapnice returned)
Authorize	customer_id you will link

1. Environment

SWAPNICE_API_BASE_URL=https://api.sandbox.swapnice.com
SWAPNICE_REDIRECT_URI=https://partner.example.com/swapnice/callback

Plus the client_id / client_secret Swapnice issued. Create a PKCE pair (code_verifier 43+ chars, code_challenge = Base64URL SHA-256).

A known-good verifier/challenge pair for a first sandbox pass:

Variable	Value
code_verifier	abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-._~
code_challenge	ImpiCd8pp4MveCNnbIS7-GXEtB0xF5HMIDoWqvGA5ig

2. Discovery

curl "$SWAPNICE_API_BASE_URL/.well-known/oauth-authorization-server"

No auth. Confirms the host is the Partner API.

3. 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": "sandbox_user_001",
    "scope": "connections:write connections:read consent:write consent:read customers:write customers:read events:write events:read profile:read claims:read intents:read webhooks:write tokens:introspect",
    "state": "sandbox-walkthrough"
  }'

scope is space-separated and must be allowed on the app. Save code. Codes expire in about 5 minutes and are single-use.

4. 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"'"
  }'

Save access_token. Optional: POST /oauth/introspect with that token (needs tokens:introspect).

5. Customer

curl -X POST "$SWAPNICE_API_BASE_URL/v1/customers" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: cust_sandbox_user_001" \
  -d '{
    "external_id": "sandbox_user_001",
    "metadata": { "source": "sandbox-walkthrough" }
  }'

Save customer.id as CUSTOMER_ID. Replaying the same idempotency key should not create a second customer.

6. Connection session

curl -X POST "$SWAPNICE_API_BASE_URL/v1/connection-sessions" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: cs_sandbox_user_001" \
  -d '{
    "customer_id": "'"$CUSTOMER_ID"'",
    "requested_purposes": ["personalization", "analytics"],
    "redirect_uri": "'"$SWAPNICE_REDIRECT_URI"'"
  }'

Save session_id. Poll GET /v1/connection-sessions/:session_id. In a white-glove sandbox, Swapnice can complete the user accept step with you.

7. Consent receipt

curl -X POST "$SWAPNICE_API_BASE_URL/v1/consent-receipts" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: cr_sandbox_user_001" \
  -d '{
    "customer_id": "'"$CUSTOMER_ID"'",
    "connection_session_id": "'"$SESSION_ID"'",
    "purposes": ["personalization", "analytics"],
    "terms_version": "2026-08-01",
    "privacy_policy_version": "2026-08-01"
  }'

Save receipt_id. Then:

curl "$SWAPNICE_API_BASE_URL/v1/customers/$CUSTOMER_ID/effective-consent" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

8. Event

Header Idempotency-Key is required.

curl -X POST "$SWAPNICE_API_BASE_URL/v1/events" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: evt_sandbox_001" \
  -d '{
    "customer_id": "'"$CUSTOMER_ID"'",
    "client_event_id": "evt_sandbox_001",
    "consent_receipt_id": "'"$RECEIPT_ID"'",
    "consent_purpose": "personalization",
    "event_type": "collection.interacted",
    "ontology": "intent",
    "ontology_category": "habit",
    "object": "ygo_series_001",
    "occurred_at": "2026-08-26T16:04:00.000Z",
    "confidence": 0.85,
    "payload": { "screen": "series_detail" },
    "context": { "platform": "sandbox" },
    "provenance": {
      "source_partner": "partner_app",
      "source_system": "sandbox",
      "collected_at": "2026-08-26T16:04:00.000Z"
    }
  }'

consent_purpose must be one you granted. Save event_id. Replay the same key — you should get the same event. Change the body on that key — you should get 409.

curl "$SWAPNICE_API_BASE_URL/v1/events/$EVENT_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Wait until status is processed before you expect profile facts.

9. Profile, claims, intents

curl "$SWAPNICE_API_BASE_URL/v1/profiles/$CUSTOMER_ID?consent_purpose=personalization" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

curl "$SWAPNICE_API_BASE_URL/v1/profiles/$CUSTOMER_ID/claims?consent_purpose=personalization" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

curl "$SWAPNICE_API_BASE_URL/v1/profiles/$CUSTOMER_ID/intents?consent_purpose=personalization" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

If these are empty, the archive has not landed. Retry the event GET, then the profile.

10. Optional: webhook, entry, revoke

curl -X POST "$SWAPNICE_API_BASE_URL/v1/webhook-endpoints" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: wh_sandbox_001" \
  -d '{
    "url": "https://webhook.site/your-unique-id",
    "enabled_events": ["event.processed", "consent.revoked"]
  }'

curl -X POST "$SWAPNICE_API_BASE_URL/v1/entries" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: en_sandbox_001" \
  -d '{
    "ontology": "ygo",
    "owner_id": "'"$CUSTOMER_ID"'",
    "ingestion_origin": "sandbox-walkthrough",
    "entry_name": "Blue-Eyes White Dragon",
    "value": 12.34,
    "fields": { "name": "Blue-Eyes White Dragon" }
  }'

curl -X POST "$SWAPNICE_API_BASE_URL/v1/consent-receipts/$RECEIPT_ID/revoke" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: rv_sandbox_001" \
  -d '{ "reason": "partner_request" }'

Revoke returns 202 and a workflow_id. Poll GET /v1/workflows/:id. A follow-up event with consent_purpose=personalization should now fail.

Cleanup: POST /oauth/revoke with { "token": "..." } and no Bearer header.

Suggested collection order

Discovery
Authorize → Token → Introspect
POST /v1/customers
POST /v1/connection-sessions → GET session
POST /v1/consent-receipts → GET effective-consent
POST /v1/events (+ Idempotency-Key) → GET event
GET /v1/profiles/:id
GET /v1/profiles/:id/claims
GET /v1/profiles/:id/intents
POST revoke → confirm 403 on a personalization read

Errors you should hit on purpose

Test	Expected
Event with no receipt	consent_required
Event for a purpose that is not granted	consent_required
Same idempotency key, different body	409 idempotency_conflict
Missing Idempotency-Key	idempotency_key_required
POST /v1/customers with customer_id instead of external_id	Validation / server error — use external_id
Expired token	401 — re-run authorize + token

When you can complete this list, you are ready for a productive integration session. Bring the request_ids from any call that surprised you.