Create a connection session - Swapnice

Create a connection session

curl --request POST \
  --url https://api.swapnice.com/v1/connection-sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "customer_id": "cust_8f2a1c",
  "requested_purposes": [
    "personalization",
    "analytics"
  ],
  "redirect_uri": "https://partner.example.com/swapnice/callback"
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    customer_id: 'cust_8f2a1c',
    requested_purposes: ['personalization', 'analytics'],
    redirect_uri: 'https://partner.example.com/swapnice/callback'
  })
};

fetch('https://api.swapnice.com/v1/connection-sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.swapnice.com/v1/connection-sessions"

payload = {
    "customer_id": "cust_8f2a1c",
    "requested_purposes": ["personalization", "analytics"],
    "redirect_uri": "https://partner.example.com/swapnice/callback"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "session": {
    "id": "cs_0b77e2",
    "app_id": "app_91b0",
    "customer_id": "cust_8f2a1c",
    "status": "created",
    "requested_purposes": [
      "personalization",
      "analytics"
    ],
    "expires_at": "2026-08-26T16:06:00.000Z",
    "created_at": "2026-08-26T16:01:00.000Z"
  },
  "client_token": "cst_example",
  "connection_url": "https://api.sandbox.swapnice.com/connect/cs_0b77e2"
}

{
  "error": {
    "code": "consent_denied",
    "message": "<string>",
    "request_id": "<string>",
    "details": [
      {
        "code": "<string>",
        "message": "<string>",
        "field": "<string>"
      }
    ]
  }
}

POST

/

v1

/

connection-sessions

Create a connection session

curl --request POST \
  --url https://api.swapnice.com/v1/connection-sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "customer_id": "cust_8f2a1c",
  "requested_purposes": [
    "personalization",
    "analytics"
  ],
  "redirect_uri": "https://partner.example.com/swapnice/callback"
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    customer_id: 'cust_8f2a1c',
    requested_purposes: ['personalization', 'analytics'],
    redirect_uri: 'https://partner.example.com/swapnice/callback'
  })
};

fetch('https://api.swapnice.com/v1/connection-sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.swapnice.com/v1/connection-sessions"

payload = {
    "customer_id": "cust_8f2a1c",
    "requested_purposes": ["personalization", "analytics"],
    "redirect_uri": "https://partner.example.com/swapnice/callback"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "session": {
    "id": "cs_0b77e2",
    "app_id": "app_91b0",
    "customer_id": "cust_8f2a1c",
    "status": "created",
    "requested_purposes": [
      "personalization",
      "analytics"
    ],
    "expires_at": "2026-08-26T16:06:00.000Z",
    "created_at": "2026-08-26T16:01:00.000Z"
  },
  "client_token": "cst_example",
  "connection_url": "https://api.sandbox.swapnice.com/connect/cs_0b77e2"
}

{
  "error": {
    "code": "consent_denied",
    "message": "<string>",
    "request_id": "<string>",
    "details": [
      {
        "code": "<string>",
        "message": "<string>",
        "field": "<string>"
      }
    ]
  }
}

Start the Plaid-Link-style account linking flow. Open connection_url for the user and poll the session. See consent and account linking.

Authorizations

Authorization

string

header

required

OAuth 2.1 authorization code with PKCE. Implicit and password flows are unsupported.

Headers

Idempotency-Key

string

required

Required for mutating requests. Replays with the same key and payload hash return the original logical result; replays with a different payload hash return 409.

Required string length: 16 - 255

X-Request-Id

string

Optional caller-supplied correlation ID echoed in responses and errors.

Body

application/json

customer_id

string

required

requested_purposes

enum<string>[]

required

Minimum array length: 1

Available options:

account_linking,

personalization,

analytics,

support,

event_enrichment,

profile_resolution,

measurement

redirect_uri

string<uri>

required

expires_in

integer

default:900

Required range: 60 <= x <= 3600

metadata

object

Response

Connection session created.

session

object

required

Show child attributes

client_token

string

required

Short-lived token for polling session status from an SDK.

connection_url

string<uri>

required