Get User Consent Status

Overview

Retrieves consent status for a user. By default returns a short summary (status only). Use ?full=true query parameter to get all consent sets with detailed consent records.

Use short mode (default) for fast status checks and access control. Use full mode for detailed consent review and compliance reporting.

Endpoint

GET https://api.baanx.com/v2/consent/user/{userId}

Headers

Header	Required	Description
`x-client-key`	✅	Your public API key
`x-us-env`	❌	Set to `true` for US region routing

Path Parameters

Parameter	Type	Required	Description
`userId`	string	✅	User identifier to retrieve consent status for

Query Parameters

Parameter	Type	Required	Description	Default
`full`	string	❌	Set to `"true"` for complete details with all consent sets	`false`

Response Modes

Short Mode (Default)

Fast response with aggregated status only:

{
  "userId": "user_123abc456def",
  "consentStatus": "complete",
  "_links": {
    "self": {
      "href": "https://api.baanx.com/v2/consent/user/user_123abc456def",
      "method": "GET"
    },
    "full": {
      "href": "https://api.baanx.com/v2/consent/user/user_123abc456def?full=true",
      "method": "GET"
    },
    "audit": {
      "href": "https://api.baanx.com/v2/consent/user/user_123abc456def/audit",
      "method": "GET"
    }
  }
}

Full Mode (?full=true)

Complete consent details including all records:

{
  "userId": "user_123abc456def",
  "consentStatus": "complete",
  "consentSets": [
    {
      "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",
            "userAgent": "Mozilla/5.0..."
          },
          "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"
        },
        {
          "consentId": "consent_003",
          "consentType": "marketingNotifications",
          "consentStatus": "granted",
          "createdAt": "2024-01-15T10:30:00Z",
          "updatedAt": "2024-01-15T10:30:00Z"
        },
        {
          "consentId": "consent_004",
          "consentType": "smsNotifications",
          "consentStatus": "denied",
          "createdAt": "2024-01-15T10:30:00Z",
          "updatedAt": "2024-01-15T10:30:00Z"
        },
        {
          "consentId": "consent_005",
          "consentType": "emailNotifications",
          "consentStatus": "granted",
          "createdAt": "2024-01-15T10:30:00Z",
          "updatedAt": "2024-01-15T10:30:00Z"
        }
      ]
    }
  ],
  "_links": {
    "self": {
      "href": "https://api.baanx.com/v2/consent/user/user_123abc456def?full=true",
      "method": "GET"
    },
    "audit": {
      "href": "https://api.baanx.com/v2/consent/user/user_123abc456def/audit",
      "method": "GET"
    }
  }
}

Status	Meaning	Action
`complete`	All required consents granted, no denials/revocations	✅ Allow access
`incomplete`	Missing required consents OR has denials/revocations	⚠️ Restrict access, prompt re-consent
`none`	No consent sets found for this user	🚫 Initiate consent collection

Status Logic:

complete: All required consents (based on policy type) have granted status
incomplete: Any required consent is missing, denied, or revoked
none: User has no consent sets (likely hasn’t completed onboarding)

Error Responses

404 Not Found

{
  "error": "Not found",
  "details": [
    "No consent sets found for userId 'user_123abc456def'"
  ]
}

Cause: User has no consent sets. They may need to complete onboarding.

498 Invalid Client Key

{
  "error": "Invalid client key",
  "details": [
    "The provided x-client-key is invalid or expired"
  ]
}

499 Missing Client Key

{
  "error": "Missing client key",
  "details": [
    "x-client-key header is required for all requests"
  ]
}

Code Examples

TypeScript - Short Mode (Access Control)

async function checkUserAccess(userId: string): Promise<boolean> {
  try {
    const response = await fetch(
      `https://api.baanx.com/v2/consent/user/${userId}`,
      {
        headers: {
          'x-client-key': process.env.BAANX_CLIENT_KEY!
        }
      }
    );

    if (!response.ok) {
      if (response.status === 404) {
        return false;
      }
      throw new Error('Failed to check consent status');
    }

    const { consentStatus } = await response.json();
    return consentStatus === 'complete';
  } catch (error) {
    console.error('Consent check failed:', error);
    return false;
  }
}

const hasAccess = await checkUserAccess('user_123abc456def');

if (!hasAccess) {
  return res.status(403).json({
    error: 'Incomplete consent',
    message: 'Please complete consent requirements'
  });
}

async function getUserConsentDetails(userId: string) {
  const response = await fetch(
    `https://api.baanx.com/v2/consent/user/${userId}?full=true`,
    {
      headers: {
        'x-client-key': process.env.BAANX_CLIENT_KEY!
      }
    }
  );

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

  const { userId: id, consentStatus, consentSets } = await response.json();

  return {
    userId: id,
    status: consentStatus,
    consents: consentSets[0]?.consents || [],
    policyType: consentSets[0]?.policyType
  };
}

const consentDetails = await getUserConsentDetails('user_123abc456def');

console.log(`User status: ${consentDetails.status}`);
console.log(`Policy: ${consentDetails.policyType}`);
console.log(`Consents: ${consentDetails.consents.length}`);

Python

import requests

def get_user_consent_status(user_id, full=False):
    url = f'https://api.baanx.com/v2/consent/user/{user_id}'
    if full:
        url += '?full=true'

    response = requests.get(
        url,
        headers={
            'x-client-key': os.getenv('BAANX_CLIENT_KEY')
        }
    )

    if response.status_code == 404:
        return {'userId': user_id, 'consentStatus': 'none'}

    response.raise_for_status()
    return response.json()

status = get_user_consent_status('user_123abc456def')

if status['consentStatus'] != 'complete':
    print('User needs to complete consent')

details = get_user_consent_status('user_123abc456def', full=True)
print(f"Consent sets: {len(details.get('consentSets', []))}")

cURL - Short Mode

curl -X GET "https://api.baanx.com/v2/consent/user/user_123abc456def" \
  -H "x-client-key: your_client_key"

cURL - Full Mode

curl -X GET "https://api.baanx.com/v2/consent/user/user_123abc456def?full=true" \
  -H "x-client-key: your_client_key"

Use Cases

Access Control & Feature Gating

Use short mode for fast status checks before allowing access:

app.use(async (req, res, next) => {
  const { consentStatus } = await getUserConsentStatus(req.user.id);

  if (consentStatus !== 'complete') {
    return res.redirect('/consent-required');
  }

  next();
});

User Privacy Dashboard

Use full mode to display user’s consent preferences:

async function renderPrivacySettings(userId: string) {
  const { consentSets } = await getUserConsentStatus(userId, true);
  const consents = consentSets[0]?.consents || [];

  return (
    <PrivacyDashboard>
      {consents.map(consent => (
        <ConsentToggle
          key={consent.consentId}
          type={consent.consentType}
          status={consent.consentStatus}
          onChange={handleConsentChange}
        />
      ))}
    </PrivacyDashboard>
  );
}

Compliance Reporting

Use full mode for compliance audits and reporting:

async function generateComplianceReport(userIds: string[]) {
  const report = {
    total: userIds.length,
    complete: 0,
    incomplete: 0,
    none: 0
  };

  for (const userId of userIds) {
    try {
      const { consentStatus } = await getUserConsentStatus(userId);
      report[consentStatus]++;
    } catch (error) {
      report.none++;
    }
  }

  return report;
}

Conditional Feature Access

Check specific consent types:

async function canSendMarketing(userId: string): Promise<boolean> {
  const { consentSets } = await getUserConsentStatus(userId, true);

  const marketingConsent = consentSets[0]?.consents.find(
    c => c.consentType === 'marketingNotifications'
  );

  return marketingConsent?.consentStatus === 'granted';
}

Performance Considerations

Short mode is optimized for high-frequency status checks (access control, API middleware). Full mode includes more data and should be used only when detailed consent information is needed.

Get Consent Audit Trail

Retrieve complete consent change history

Revoke Consent

Allow users to withdraw consents

Get Consent Set by ID

Retrieve specific consent set details

Implementation Guide

Full integration guide

​Overview

​Endpoint

​Headers

​Path Parameters

​Query Parameters

​Response Modes

​Short Mode (Default)

​Full Mode (?full=true)

​Consent Status Values

​Error Responses

​404 Not Found

​498 Invalid Client Key

​499 Missing Client Key

​Code Examples

​TypeScript - Short Mode (Access Control)

​TypeScript - Full Mode (Consent Dashboard)

​Python

​cURL - Short Mode

​cURL - Full Mode

​Use Cases

​Performance Considerations

​Related Endpoints

Get Consent Audit Trail

Revoke Consent

Get Consent Set by ID

Implementation Guide

Overview

Endpoint

Headers

Path Parameters

Query Parameters

Response Modes

Short Mode (Default)

Full Mode (?full=true)

Consent Status Values

Error Responses

404 Not Found

498 Invalid Client Key

499 Missing Client Key

Code Examples

TypeScript - Short Mode (Access Control)

TypeScript - Full Mode (Consent Dashboard)

Python

cURL - Short Mode

cURL - Full Mode

Use Cases

Performance Considerations

Related Endpoints