Skip to main content
GET
/
v1
/
auth
/
settings
Get Registration Settings
curl --request GET \
  --url https://dev.api.baanx.com/v1/auth/settings \
  --header 'x-client-key: <x-client-key>'
{
  "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

​
x-client-key
string
required
Your public API client key
​
x-us-env
boolean
Set to true to get US-specific settingsDefault: false

​
Response

​
countries
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
​
usStates
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
​
links
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
​
config
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

{
  "message": "Invalid request parameters"
}

{
  "message": "Invalid 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"

​
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 };
}

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.