Skip to main content

Setting brand and locale

You can assign brand and locale values to users when creating them or by updating existing users. Both root usersRoot user The individual who creates the identity. For corporate identities, the root user needs to be a legal representative of the corporate such as a director or a representative who has the power of attorney over the company. For consumer identities, the root user is the owner of the identity. Every identity must always have one root user. (consumer or corporate) and authorized users support these fields.

For an explanation of how brand and locale affect template selection, see the cascading template selection logic.

Locale​

Locale determines the language of communications sent to your users. We use the BCP 47 standard for locale codes, such as en-GB for British English, fr-FR for French (France), or de-DE for German. The value is optional—if not specified, the user receives communications from your default templates.

Brand​

Brand represents an arbitrary grouping that you define for branding purposes. This is useful when you operate multiple distinct brands within your program—for example, a premium brand and a standard brand, or regional brands for different markets. Brand values can be up to 25 characters with no spaces and are also optional.

Creating users with brand and locale​

When creating a new consumer or corporate root userRoot user The individual who creates the identity. For corporate identities, the root user needs to be a legal representative of the corporate such as a director or a representative who has the power of attorney over the company. For consumer identities, the root user is the owner of the identity. Every identity must always have one root user., include the locale and brand fields in your request body.

For a consumer root userRoot user The individual who creates the identity. For corporate identities, the root user needs to be a legal representative of the corporate such as a director or a representative who has the power of attorney over the company. For consumer identities, the root user is the owner of the identity. Every identity must always have one root user., your POST request to /consumers might include:

POST/consumersTry it 
{
  "profileId": "string",
  "tag": "string",
  "rootUser": {
    "name": "string",
    "surname": "string",
    "email": "user@example.com",
    "mobile": {
      "countryCode": "stri",
      "number": "string"
    },
    "dateOfBirth": {
      "year": 1900,
      "month": 1,
      "day": 1
    },
    "occupation": "ACCOUNTING",
    "address": {
      "addressLine1": "string",
      "addressLine2": "string",
      "city": "string",
      "postCode": "string",
      "state": "string",
      "country": "st"
    },
    "placeOfBirth": "string",
    "nationality": "st",
    "tag": "string"
  },
  "ipAddress": "string",
  "acceptedTerms": true,
  "baseCurrency": "str",
  "feeGroup": "string",
  "sourceOfFunds": "PERSONAL_SAVINGS",
  "sourceOfFundsOther": "string"
}
{
  "rootUser": {
    "name": "Jean",
    "surname": "Dupont",
    "email": "jean.dupont@example.com",
    "mobile": {
      "countryCode": "33",
      "number": "612345678"
    },
    "locale": "fr-FR",
    "brand": "PremiumGold"
  }
}

For a corporate root userRoot user The individual who creates the identity. For corporate identities, the root user needs to be a legal representative of the corporate such as a director or a representative who has the power of attorney over the company. For consumer identities, the root user is the owner of the identity. Every identity must always have one root user., the POST request to /corporates follows the same pattern with the locale and brand fields nested within the rootUser object.

POST/corporatesTry it 
{
  "profileId": "string",
  "tag": "string",
  "rootUser": {
    "name": "string",
    "surname": "string",
    "email": "user@example.com",
    "mobile": {
      "countryCode": "stri",
      "number": "string"
    },
    "companyPosition": "DIRECTOR",
    "dateOfBirth": {
      "year": 1900,
      "month": 1,
      "day": 1
    },
    "tag": "string"
  },
  "company": {
    "type": "SOLE_TRADER",
    "businessAddress": {
      "addressLine1": "string",
      "addressLine2": "string",
      "city": "string",
      "postCode": "string",
      "state": "string",
      "country": "st"
    },
    "name": "string",
    "registrationNumber": "string",
    "registrationCountry": "st"
  },
  "industry": "ACCOUNTING",
  "sourceOfFunds": "LABOUR_CONTRACT",
  "sourceOfFundsOther": "string",
  "acceptedTerms": true,
  "ipAddress": "string",
  "baseCurrency": "str",
  "feeGroup": "string"
}

When creating authorized users via POST to /users, the fields are included at the top level:

POST/usersTry it 
{
  "name": "string",
  "surname": "string",
  "email": "user@example.com",
  "mobile": {
    "countryCode": "stri",
    "number": "string"
  },
  "dateOfBirth": {
    "year": 1900,
    "month": 1,
    "day": 1
  },
  "tag": "string"
}
{
  "name": "Marie",
  "surname": "Laurent",
  "email": "marie.laurent@example.com",
  "locale": "fr-CA",
  "brand": "StandardPlus"
}

Updating existing users​

To update the locale or brand for an existing user, use the PATCH endpoints:

  • For consumer root usersRoot user The individual who creates the identity. For corporate identities, the root user needs to be a legal representative of the corporate such as a director or a representative who has the power of attorney over the company. For consumer identities, the root user is the owner of the identity. Every identity must always have one root user., send a PATCH request to /consumers.
  • For corporate root usersRoot user The individual who creates the identity. For corporate identities, the root user needs to be a legal representative of the corporate such as a director or a representative who has the power of attorney over the company. For consumer identities, the root user is the owner of the identity. Every identity must always have one root user., use /corporates.
  • For authorized users, use /users/${USER_ID}.

For example, to update an authorized user's locale:

PATCH /users/${USER_ID}
{
  "locale": "de-DE"
}

You can update locale and brand independently; you don't need to provide both values if you only want to change one.

Retrieving user information​

The GET endpoints for /consumers, /corporates, /users, and /users/${USER_ID} return the locale and brand values if they have been set for the user.

Locale strategy​

Decide whether you need regional variants (for example, en-GB versus en-US) or can use a single base locale (for example, en) for each language. Using base locales simplifies template management while still serving users with regional locale settings through the locale fallback mechanism.

Common approaches for assigning locale include:

  • Deriving locale from the user's browser settings or app language preference
  • Capturing the user's language choice during registration
  • Defaulting to a regional locale based on the user's country

Brand strategy​

Since brand is a free-form field (up to 25 characters, no spaces), establish a naming convention and document it internally. Typos in brand values when creating users cause those users to fall back to non-branded templates.

Common approaches for assigning brand include:

  • Deriving brand from the context in which the user registered (for example, which product or sub-brand they signed up through)
  • Setting brand based on the user's tier or segment
  • Using brand to distinguish between regional operations