Get Registration Settings

curl --request GET \
  --url https://dev.api.baanx.com/v1/auth/settings \
  --header 'x-client-key: <x-client-key>'

const options = {method: 'GET', headers: {'x-client-key': '<x-client-key>'}};

fetch('https://dev.api.baanx.com/v1/auth/settings', 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://dev.api.baanx.com/v1/auth/settings",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-client-key: <x-client-key>"
  ],
]);

$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://dev.api.baanx.com/v1/auth/settings"

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

	req.Header.Add("x-client-key", "<x-client-key>")

	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://dev.api.baanx.com/v1/auth/settings")

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

request = Net::HTTP::Get.new(url)
request["x-client-key"] = '<x-client-key>'

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

{
  "countries": [
    {}
  ],
  "usStates": [
    {}
  ],
  "links": {},
  "config": {}
}

GET

auth

settings

Get Registration Settings

curl --request GET \
  --url https://dev.api.baanx.com/v1/auth/settings \
  --header 'x-client-key: <x-client-key>'

const options = {method: 'GET', headers: {'x-client-key': '<x-client-key>'}};

fetch('https://dev.api.baanx.com/v1/auth/settings', 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://dev.api.baanx.com/v1/auth/settings",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-client-key: <x-client-key>"
  ],
]);

$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://dev.api.baanx.com/v1/auth/settings"

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

	req.Header.Add("x-client-key", "<x-client-key>")

	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://dev.api.baanx.com/v1/auth/settings")

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

request = Net::HTTP::Get.new(url)
request["x-client-key"] = '<x-client-key>'

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

{
  "countries": [
    {}
  ],
  "usStates": [
    {}
  ],
  "links": {},
  "config": {}
}

Overview

Retrieve all configuration settings required for user registration. This endpoint provides:

Countries: List of supported countries with calling codes and signup availability
US States: List of US states with postal abbreviations (for US registrations)
Legal Links: Terms & conditions, privacy policies, disclosures by region
Configuration: Email validation settings, SMS consent numbers, support contacts

This data is typically fetched once when loading your registration form and used to populate dropdowns, display legal documents, and configure validation rules.

Data is cached per environment and refreshed hourly. US-specific data only returned if your environment supports the US region.

When to Use

Loading registration form for the first time
Populating country/state dropdown menus
Displaying region-appropriate legal documents
Configuring email domain validation rules
Showing SMS consent information

Request

Headers

string

required

Your public API client key

boolean

Set to true to get US-specific settingsDefault: false

Response

array

required

List of supported countries for registrationEach country object contains:

id - Unique identifier (UUID)
iso3166alpha2 - ISO 3166-1 alpha-2 country code (e.g., US, GB)
name - Country name (e.g., United States of America)
callingCode - International dialing code without + (e.g., 1, 44)
canSignUp - Whether registration is enabled for this country

array

required

List of US states (only for US-supported environments)Each state object contains:

id - Unique identifier (UUID)
name - State name (e.g., Alaska)
postalAbbreviation - 2-letter postal code (e.g., AK)
canSignUp - Whether registration is enabled for this state

object

required

Legal document URLs by regionStructure:

us - US-specific legal documents (null if not supported)
- termsAndConditions - Terms of service URL
- accountOpeningDisclosure - Account disclosure URL
- noticeOfPrivacy - Privacy policy URL
- eSignConsentDisclosure - E-signature consent disclosure URL
intl - International legal documents
- termsAndConditions - Terms of service URL
- rightToInformation - Information rights URL

object

required

Environment-specific configuration settingsStructure:

us - US configuration (null if not supported)
- emailSpecialCharactersDomainsException - Domains allowing special chars in email
- consentSmsNumber - SMS number for opt-in consent
- supportEmail - Support contact email
intl - International configuration
- Same fields as US config

Success Response

{
  "countries": [
    {
      "id": "90b91481-1f6f-4a60-a976-2354a010f4aa",
      "iso3166alpha2": "US",
      "name": "United States of America",
      "callingCode": "1",
      "canSignUp": true
    }
  ],
  "usStates": [
    {
      "id": "90b91481-1f6f-4a60-a976-2354a010f4aa",
      "name": "Alaska",
      "postalAbbreviation": "AK",
      "canSignUp": true
    }
  ],
  "links": {
    "us": {
      "termsAndConditions": "https://example.com/terms",
      "accountOpeningDisclosure": "https://example.com/disclosure",
      "noticeOfPrivacy": "https://example.com/privacy",
      "eSignConsentDisclosure": "https://example.com/esign-consent"
    },
    "intl": {
      "termsAndConditions": "https://example.com/terms",
      "rightToInformation": "https://example.com/info"
    }
  },
  "config": {
    "us": {
      "emailSpecialCharactersDomainsException": "baanx.com",
      "consentSmsNumber": "123456",
      "supportEmail": "support@example.com"
    },
    "intl": {
      "emailSpecialCharactersDomainsException": "baanx.com",
      "consentSmsNumber": "123456",
      "supportEmail": "support@example.com"
    }
  }
}

Error Responses

400 Bad Request

{
  "message": "Invalid request parameters"
}

498 Invalid Client Key

{
  "message": "Invalid client key"
}

499 Missing Client Key

{
  "message": "Missing client key"
}

Code Examples

curl -X GET "https://api.example.com/v1/auth/settings" \
  -H "x-client-key: your-client-key"

async function loadRegistrationSettings() {
  const response = await fetch('https://api.example.com/v1/auth/settings', {
    headers: {
      'x-client-key': 'your-client-key'
    }
  });

  const settings = await response.json();

  // Populate country dropdown
  const countrySelect = document.getElementById('country');
  settings.countries
    .filter(c => c.canSignUp)
    .forEach(country => {
      const option = document.createElement('option');
      option.value = country.iso3166alpha2;
      option.textContent = country.name;
      option.dataset.callingCode = country.callingCode;
      countrySelect.appendChild(option);
    });

  // Populate US states dropdown (if applicable)
  if (settings.usStates.length > 0) {
    const stateSelect = document.getElementById('state');
    settings.usStates
      .filter(s => s.canSignUp)
      .forEach(state => {
        const option = document.createElement('option');
        option.value = state.postalAbbreviation;
        option.textContent = state.name;
        stateSelect.appendChild(option);
      });
  }

  // Display legal links
  const isUS = detectUserRegion() === 'US';
  const links = isUS ? settings.links.us : settings.links.intl;

  document.getElementById('terms-link').href = links.termsAndConditions;
  if (isUS) {
    document.getElementById('disclosure-link').href = links.accountOpeningDisclosure;
    document.getElementById('privacy-link').href = links.noticeOfPrivacy;
  }

  // Store config for validation
  sessionStorage.setItem('registrationConfig', JSON.stringify(settings.config));

  return settings;
}

import { useState, useEffect } from 'react';

interface Country {
  id: string;
  iso3166alpha2: string;
  name: string;
  callingCode: string;
  canSignUp: boolean;
}

interface USState {
  id: string;
  name: string;
  postalAbbreviation: string;
  canSignUp: boolean;
}

interface RegistrationSettings {
  countries: Country[];
  usStates: USState[];
  links: {
    us: any;
    intl: any;
  };
  config: {
    us: any;
    intl: any;
  };
}

export function useRegistrationSettings() {
  const [settings, setSettings] = useState<RegistrationSettings | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<Error | null>(null);

  useEffect(() => {
    async function fetchSettings() {
      try {
        const response = await fetch('https://api.example.com/v1/auth/settings', {
          headers: {
            'x-client-key': process.env.NEXT_PUBLIC_CLIENT_KEY!
          }
        });

        if (!response.ok) {
          throw new Error('Failed to fetch registration settings');
        }

        const data = await response.json();
        setSettings(data);
      } catch (err) {
        setError(err as Error);
      } finally {
        setLoading(false);
      }
    }

    fetchSettings();
  }, []);

  return { settings, loading, error };
}

// Usage in component
function RegistrationForm() {
  const { settings, loading, error } = useRegistrationSettings();

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <form>
      <select name="country">
        {settings?.countries
          .filter(c => c.canSignUp)
          .map(country => (
            <option key={country.id} value={country.iso3166alpha2}>
              {country.name}
            </option>
          ))
        }
      </select>

      <select name="state">
        {settings?.usStates
          .filter(s => s.canSignUp)
          .map(state => (
            <option key={state.id} value={state.postalAbbreviation}>
              {state.name}
            </option>
          ))
        }
      </select>
    </form>
  );
}

import requests
from typing import Dict, Any
from datetime import datetime, timedelta

class RegistrationSettingsCache:
    def __init__(self, client_key: str):
        self.client_key = client_key
        self.cache: Dict[str, Any] = {}
        self.cache_expiry: datetime = datetime.min

    def get_settings(self, region: str = 'intl') -> Dict[str, Any]:
        # Check cache validity (1 hour)
        if datetime.now() > self.cache_expiry:
            self._refresh_cache()

        return self.cache

    def _refresh_cache(self):
        response = requests.get(
            'https://api.example.com/v1/auth/settings',
            headers={'x-client-key': self.client_key}
        )

        if response.status_code == 200:
            self.cache = response.json()
            self.cache_expiry = datetime.now() + timedelta(hours=1)
        else:
            raise Exception(f"Failed to fetch settings: {response.status_code}")

    def get_country_by_code(self, code: str) -> Dict[str, Any]:
        for country in self.cache.get('countries', []):
            if country['iso3166alpha2'] == code:
                return country
        return None

    def get_allowed_countries(self) -> list:
        return [
            c for c in self.cache.get('countries', [])
            if c.get('canSignUp', False)
        ]

# Usage
settings_cache = RegistrationSettingsCache('your-client-key')
settings = settings_cache.get_settings()

allowed_countries = settings_cache.get_allowed_countries()
print(f"Registration enabled for {len(allowed_countries)} countries")

Implementation Patterns

Dynamic Phone Number Formatting

function formatPhoneNumberWithCountry(countryCode, phoneNumber, settings) {
  const country = settings.countries.find(c => c.iso3166alpha2 === countryCode);

  if (!country) return phoneNumber;

  return `+${country.callingCode}${phoneNumber}`;
}

// Usage in registration form
const formattedPhone = formatPhoneNumberWithCountry(
  selectedCountry,
  phoneInput.value,
  settings
);

Email Validation with Exceptions

function validateEmail(email, settings, region) {
  const config = region === 'us' ? settings.config.us : settings.config.intl;
  const exceptionDomains = config.emailSpecialCharactersDomainsException.split(',');

  const [localPart, domain] = email.split('@');

  // Check if domain allows special characters
  const allowSpecialChars = exceptionDomains.some(d => domain.includes(d.trim()));

  if (!allowSpecialChars) {
    // Validate no special characters except . and -
    const hasInvalidChars = /[^a-zA-Z0-9.\-]/.test(localPart);
    if (hasInvalidChars) {
      return {
        valid: false,
        error: 'Email contains invalid characters'
      };
    }
  }

  return { valid: true };
}

Legal Document Display

function displayLegalLinks(settings, userRegion) {
  const links = userRegion === 'US' ? settings.links.us : settings.links.intl;

  return `
    <div class="legal-links">
      <p>By registering, you agree to our:</p>
      <ul>
        <li><a href="${links.termsAndConditions}" target="_blank">Terms and Conditions</a></li>
        ${userRegion === 'US' ? `
          <li><a href="${links.accountOpeningDisclosure}" target="_blank">Account Opening Disclosure</a></li>
          <li><a href="${links.noticeOfPrivacy}" target="_blank">Notice of Privacy</a></li>
          <li><a href="${links.eSignConsentDisclosure}" target="_blank">E-Sign Consent Disclosure</a></li>
        ` : `
          <li><a href="${links.rightToInformation}" target="_blank">Right to Information</a></li>
        `}
      </ul>
    </div>
  `;
}

Edge Cases and Important Notes

Caching: Settings are cached server-side and updated hourly. Your application should also cache this data locally to minimize API calls.

Country Availability: Always check canSignUp flag before allowing registration. Some countries may be temporarily disabled for regulatory reasons.

Performance: Fetch settings once when loading the registration page and store in memory. Don’t fetch on every form submission.

Handling Region-Specific Requirements

Different regions have different requirements: US Requirements:

SSN field required
US state selection required
Separate mailing address option
Specific legal disclosures

International Requirements:

No SSN field
No state selection
Mailing address same as physical
Different legal documents

function getRequiredFields(countryCode, settings) {
  const isUS = countryCode === 'US';

  return {
    email: true,
    password: true,
    phone: true,
    firstName: true,
    lastName: true,
    dateOfBirth: true,
    nationality: true,
    ssn: isUS,
    address: true,
    city: true,
    zip: true,
    state: isUS,
    mailingAddress: isUS ? 'optional' : false
  };
}

Empty States Handling

Some environments may not support certain features:

if (settings.usStates && settings.usStates.length > 0) {
  // Show US state dropdown
  renderStateDropdown(settings.usStates);
} else {
  // Hide state dropdown for non-US environment
  hideStateField();
}

if (settings.links.us) {
  // US region is supported
  showUSLegalLinks(settings.links.us);
}

Send Email Verification

Start registration process

Registration Guide

Complete user registration guide

The response includes lists of supported countries (with ISO 3166-1 alpha-2 codes) and US states (with postal abbreviations) that you can use to populate registration form dropdowns and validate user input.

Overview

Authentication

User

Card

Orders

Wallet

Delegation

Consent

Referral

Webhooks

Get Registration Settings

Overview

When to Use

Request

Headers

Response

Success Response

Error Responses

Code Examples

Implementation Patterns

Dynamic Phone Number Formatting

Email Validation with Exceptions

Legal Document Display

Edge Cases and Important Notes

Handling Region-Specific Requirements

Empty States Handling

Send Email Verification

Registration Guide

​Overview

​When to Use

​Request

​Headers

​Response

​Success Response

​Error Responses

​Code Examples

​Implementation Patterns

​Dynamic Phone Number Formatting

​Email Validation with Exceptions

​Legal Document Display

​Edge Cases and Important Notes

​Handling Region-Specific Requirements

​Empty States Handling

​Related Documentation

Send Email Verification

Registration Guide

Overview

When to Use

Request

Headers

Response

Success Response

Error Responses

Code Examples

Implementation Patterns

Dynamic Phone Number Formatting

Email Validation with Exceptions

Legal Document Display

Edge Cases and Important Notes

Handling Region-Specific Requirements

Empty States Handling

Related Documentation