Skip to main content
PATCH
/
v2
/
consent
/
onboarding
/
{consentSetId}
Link User to Consent Set
curl --request PATCH \
  --url https://api.example.com/v2/consent/onboarding/{consentSetId}

​
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

1

After User Account Creation

Once you have a permanent userId from your system
2

After Email Verification

When user verifies their email and account is activated
3

After KYC Completion

When identity verification finalizes
4

Registration Complete

When the full registration workflow finishes

​
Endpoint

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

​
Headers

HeaderRequiredDescription
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

ParameterTypeRequiredDescription
consentSetIdstring (UUID)✅UUID of the consent set to link (from create response)

​
Request Body

ParameterTypeRequiredDescription
userIdstring✅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 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);
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;
  }
}
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