Link User to Consent Set

curl --request PATCH \
  --url https://api.example.com/v2/consent/onboarding/{consentSetId}

const options = {method: 'PATCH'};

fetch('https://api.example.com/v2/consent/onboarding/{consentSetId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v2/consent/onboarding/{consentSetId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v2/consent/onboarding/{consentSetId}"

	req, _ := http.NewRequest("PATCH", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v2/consent/onboarding/{consentSetId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)

response = http.request(request)
puts response.read_body

PATCH

consent

onboarding

{consentSetId}

Link User to Consent Set

curl --request PATCH \
  --url https://api.example.com/v2/consent/onboarding/{consentSetId}

const options = {method: 'PATCH'};

fetch('https://api.example.com/v2/consent/onboarding/{consentSetId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v2/consent/onboarding/{consentSetId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v2/consent/onboarding/{consentSetId}"

	req, _ := http.NewRequest("PATCH", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v2/consent/onboarding/{consentSetId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)

response = http.request(request)
puts response.read_body

Overview

Links a permanent userId to an existing consent set that was created during onboarding. This endpoint completes the consent onboarding process by associating consent records with a user account.

Call this endpoint after user account creation is complete (e.g., after email verification, KYC completion, or registration finalization).

When to Use

After User Account Creation

Once you have a permanent userId from your system

After Email Verification

When user verifies their email and account is activated

After KYC Completion

When identity verification finalizes

Registration Complete

When the full registration workflow finishes

Endpoint

PATCH https://api.baanx.com/v2/consent/onboarding/{consentSetId}

Headers

Header	Required	Description
`x-client-key`	✅	Your public API key
`x-secret-key`	✅	Your secret API key
`Content-Type`	✅	Must be `application/json`
`x-us-env`	❌	Set to `true` for US region routing

Path Parameters

Parameter	Type	Required	Description
`consentSetId`	string (UUID)	✅	UUID of the consent set to link (from create response)

Request Body

Parameter	Type	Required	Description
`userId`	string	✅	Permanent user identifier to link to this consent set

Example Request

{
  "userId": "user_123abc456def"
}

Response

200 OK

{
  "consentSetId": "550e8400-e29b-41d4-a716-446655440001",
  "userId": "user_123abc456def",
  "completedAt": "2024-01-15T10:35:00Z",
  "consentSet": {
    "consentSetId": "550e8400-e29b-41d4-a716-446655440001",
    "userId": "user_123abc456def",
    "onboardingId": "onboarding_abc123xyz",
    "tenantId": "tenant_baanx_prod",
    "policyType": "global",
    "completedAt": "2024-01-15T10:35:00Z",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:35:00Z",
    "consents": [
      {
        "consentId": "consent_001",
        "consentType": "eSignAct",
        "consentStatus": "granted",
        "metadata": {
          "timestamp": "2024-01-15T10:30:00Z",
          "ipAddress": "192.168.1.1"
        },
        "createdAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-15T10:30:00Z"
      },
      {
        "consentId": "consent_002",
        "consentType": "termsAndPrivacy",
        "consentStatus": "granted",
        "metadata": {
          "timestamp": "2024-01-15T10:30:00Z"
        },
        "createdAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-15T10:30:00Z"
      }
    ]
  },
  "_links": {
    "self": {
      "href": "https://api.baanx.com/v2/consent/consentSet/550e8400-e29b-41d4-a716-446655440001",
      "method": "GET"
    },
    "audit": {
      "href": "https://api.baanx.com/v2/consent/user/user_123abc456def/audit",
      "method": "GET"
    }
  }
}

400 Bad Request

{
  "error": "Validation error",
  "details": [
    "userId is required and must not be empty"
  ]
}

404 Not Found

{
  "error": "Not found",
  "details": [
    "Consent set with ID '550e8400-e29b-41d4-a716-446655440001' not found"
  ]
}

409 Conflict

{
  "error": "Conflict",
  "details": [
    "This consent set is already linked to userId 'user_123abc456def'"
  ]
}

A consent set can only be linked to one user. Attempting to link again will result in a 409 Conflict error.

Code Examples

TypeScript

async function linkUserToConsent(consentSetId: string, userId: string) {
  const response = await fetch(
    `https://api.baanx.com/v2/consent/onboarding/${consentSetId}`,
    {
      method: 'PATCH',
      headers: {
        'Content-Type': 'application/json',
        'x-client-key': process.env.BAANX_CLIENT_KEY!,
        'x-secret-key': process.env.BAANX_SECRET_KEY!
      },
      body: JSON.stringify({ userId })
    }
  );

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`Linking failed: ${error.details.join(', ')}`);
  }

  return response.json();
}

const result = await linkUserToConsent(
  '550e8400-e29b-41d4-a716-446655440001',
  'user_123abc456def'
);

console.log(`User ${result.userId} linked to consent set ${result.consentSetId}`);

Python

import requests

def link_user_to_consent(consent_set_id, user_id):
    response = requests.patch(
        f'https://api.baanx.com/v2/consent/onboarding/{consent_set_id}',
        headers={
            'Content-Type': 'application/json',
            'x-client-key': os.getenv('BAANX_CLIENT_KEY'),
            'x-secret-key': os.getenv('BAANX_SECRET_KEY')
        },
        json={'userId': user_id}
    )

    response.raise_for_status()
    return response.json()

result = link_user_to_consent(
    '550e8400-e29b-41d4-a716-446655440001',
    'user_123abc456def'
)

print(f"User {result['userId']} linked successfully")

cURL

curl -X PATCH https://api.baanx.com/v2/consent/onboarding/550e8400-e29b-41d4-a716-446655440001 \
  -H "Content-Type: application/json" \
  -H "x-client-key: your_client_key" \
  -H "x-secret-key: your_secret_key" \
  -d '{
    "userId": "user_123abc456def"
  }'

Integration Workflow

Best Practices

Store ConsentSetId Temporarily

Store the consentSetId in your session or database until user registration completes:

await sessionStore.set(`consent_${onboardingId}`, consentSetId);

const storedConsentSetId = await sessionStore.get(`consent_${onboardingId}`);
await linkUserToConsent(storedConsentSetId, userId);

Handle Idempotency

Check if linking has already occurred before attempting:

async function linkUserIfNeeded(consentSetId: string, userId: string) {
  try {
    return await linkUserToConsent(consentSetId, userId);
  } catch (error) {
    if (error.status === 409) {
      const consentSet = await getConsentSetById(consentSetId);
      if (consentSet.userId === userId) {
        console.log('Already linked to this user');
        return consentSet;
      }
      throw new Error('Consent set linked to different user');
    }
    throw error;
  }
}

Clean Up After Linking

Remove temporary data after successful linking:

const result = await linkUserToConsent(consentSetId, userId);
await sessionStore.delete(`consent_${onboardingId}`);

Important Notes

One-Time Operation: Each consent set can only be linked once. The linking action is recorded in the audit trail and cannot be undone.

Audit Trail: The linking action is automatically recorded in the user’s consent audit trail with timestamp and metadata.

Create Onboarding Consent

Create the initial consent set

Get User Consent Status

Check user’s consent status after linking

Get Consent Set by ID

Retrieve consent set details

Implementation Guide

Full integration guide

Overview

Authentication

User

Card

Orders

Wallet

Delegation

Consent

Referral

Webhooks

Link User to Consent Set

Overview

When to Use

Endpoint

Headers

Path Parameters

Request Body

Example Request

Response

200 OK

400 Bad Request

404 Not Found

409 Conflict

Code Examples

TypeScript

Python

cURL

Integration Workflow

Best Practices

Important Notes

Create Onboarding Consent

Get User Consent Status

Get Consent Set by ID

Implementation Guide

​Overview

​When to Use

​Endpoint

​Headers

​Path Parameters

​Request Body

​Example Request

​Response

​200 OK

​400 Bad Request

​404 Not Found

​409 Conflict

​Code Examples

​TypeScript

​Python

​cURL

​Integration Workflow

​Best Practices

​Important Notes

​Related Endpoints

Create Onboarding Consent

Get User Consent Status

Get Consent Set by ID

Implementation Guide

Overview

When to Use

Endpoint

Headers

Path Parameters

Request Body

Example Request

Response

200 OK

400 Bad Request

404 Not Found

409 Conflict

Code Examples

TypeScript

Python

cURL

Integration Workflow

Best Practices

Important Notes

Related Endpoints