> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baanx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Registration Settings

> Retrieve configuration settings required for building registration forms

## 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.

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

## 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

<ParamField header="x-client-key" type="string" required>
  Your public API client key
</ParamField>

<ParamField header="x-us-env" type="boolean">
  Set to `true` to get US-specific settings

  **Default**: `false`
</ParamField>

## Response

<ResponseField name="countries" type="array" required>
  List of supported countries for registration

  Each 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
</ResponseField>

<ResponseField name="usStates" type="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
</ResponseField>

<ResponseField name="links" type="object" required>
  Legal document URLs by region

  **Structure**:

  * `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
</ResponseField>

<ResponseField name="config" type="object" required>
  Environment-specific configuration settings

  **Structure**:

  * `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
</ResponseField>

### Success Response

```json theme={null}
{
  "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

<Accordion title="400 Bad Request">
  ```json theme={null}
  {
    "message": "Invalid request parameters"
  }
  ```
</Accordion>

<Accordion title="498 Invalid Client Key">
  ```json theme={null}
  {
    "message": "Invalid client key"
  }
  ```
</Accordion>

<Accordion title="499 Missing Client Key">
  ```json theme={null}
  {
    "message": "Missing client key"
  }
  ```
</Accordion>

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.example.com/v1/auth/settings" \
    -H "x-client-key: your-client-key"
  ```

  ```javascript JavaScript - Registration Form theme={null}
  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;
  }
  ```

  ```typescript TypeScript - React Hook theme={null}
  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>
    );
  }
  ```

  ```python Python - Cache Settings theme={null}
  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")
  ```
</CodeGroup>

## Implementation Patterns

### Dynamic Phone Number Formatting

```javascript theme={null}
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

```javascript theme={null}
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

```javascript theme={null}
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

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

<Warning>
  **Country Availability**: Always check `canSignUp` flag before allowing registration. Some countries may be temporarily disabled for regulatory reasons.
</Warning>

<Tip>
  **Performance**: Fetch settings once when loading the registration page and store in memory. Don't fetch on every form submission.
</Tip>

### 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

```javascript theme={null}
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:

```javascript theme={null}
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);
}
```

## Related Documentation

<CardGroup cols={2}>
  <Card title="Send Email Verification" icon="envelope" href="/api-reference/auth/register-email-send">
    Start registration process
  </Card>

  <Card title="Registration Guide" icon="user-plus" href="/guides/user/registration">
    Complete user registration guide
  </Card>
</CardGroup>

<Note>
  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.
</Note>