Setting brand and locale

You can assign brand and locale values to users when creating them or by updating existing users. Both root usersRoot userThe individual who creates the customer. For corporates, the root user needs to be a legal representative of the company, such as a director or someone with power of attorney. For consumers, the root user is the customer. Every customer must always have one root user. (consumer or corporate) and authorized usersAuthorized UserAn individual that has been invited by the root user to manage a customer's instruments and transactions. They are not the legal owner of the customer but can be granted access to perform operations on its behalf. For corporates, card assignees are created as Authorized Users. US-English variant of _Authorised User_. 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 userThe individual who creates the customer. For corporates, the root user needs to be a legal representative of the company, such as a director or someone with power of attorney. For consumers, the root user is the customer. Every customer must always have one root user., include the locale and brand fields in your request body.

For a consumer root userRoot userThe individual who creates the customer. For corporates, the root user needs to be a legal representative of the company, such as a director or someone with power of attorney. For consumers, the root user is the customer. Every customer must always have one root user., your POST request to /consumers might include:

POST/consumersOpen API reference →

/consumers

{  "profileId": "10001",  "tag": "customer-123",  "rootUser": {    "name": "string",    "surname": "string",    "email": "[email protected]",    "mobile": {      "countryCode": "+44",      "number": "7700900123"    },    "dateOfBirth": {      "year": 1990,      "month": 1,      "day": 1    },    "occupation": "ACCOUNTING",    "address": {      "addressLine1": "1 High Street",      "addressLine2": "Flat 2",      "city": "London",      "postCode": "W1A 1AA",      "state": "Greater London",      "country": "GB"    },    "placeOfBirth": "string",    "nationality": {},    "tag": {},    "locale": "en-GB",    "brand": "Acme"  },  "ipAddress": "string",  "acceptedTerms": true,  "baseCurrency": "GBP",  "feeGroup": "string",  "sourceOfFunds": "PERSONAL_SAVINGS",  "sourceOfFundsOther": "string"}

{
  "rootUser": {
    "name": "Jean",
    "surname": "Dupont",
    "email": "[email protected]",
    "mobile": {
      "countryCode": "33",
      "number": "612345678"
    },
    "locale": "fr-FR",
    "brand": "PremiumGold"
  }
}

For a corporate root userRoot userThe individual who creates the customer. For corporates, the root user needs to be a legal representative of the company, such as a director or someone with power of attorney. For consumers, the root user is the customer. Every customer 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/corporatesOpen API reference →

/corporates

{  "profileId": "10001",  "tag": "customer-123",  "rootUser": {    "name": "string",    "surname": "string",    "email": "[email protected]",    "mobile": {      "countryCode": "+44",      "number": "7700900123"    },    "companyPosition": "DIRECTOR",    "dateOfBirth": {      "year": 1990,      "month": 1,      "day": 1    },    "tag": "customer-123",    "locale": "en-GB",    "brand": "Acme"  },  "company": {    "type": "SOLE_TRADER",    "businessAddress": {      "addressLine1": "1 High Street",      "addressLine2": "Flat 2",      "city": "London",      "postCode": "W1A 1AA",      "state": "Greater London",      "country": "GB"    },    "name": "string",    "registrationNumber": "string",    "registrationCountry": "string"  },  "industry": "ACCOUNTING",  "sourceOfFunds": "LABOUR_CONTRACT",  "sourceOfFundsOther": "string",  "acceptedTerms": true,  "ipAddress": "string",  "baseCurrency": "GBP",  "feeGroup": "string"}

When creating authorized usersAuthorized UserAn individual that has been invited by the root user to manage a customer's instruments and transactions. They are not the legal owner of the customer but can be granted access to perform operations on its behalf. For corporates, card assignees are created as Authorized Users. US-English variant of _Authorised User_. via POST to /users, the fields are included at the top level:

POST/usersOpen API reference →

/users

{  "name": "Alex",  "surname": "Smith",  "email": "[email protected]",  "mobile": {    "countryCode": "+44",    "number": "7700900123"  },  "dateOfBirth": {    "year": 1990,    "month": 1,    "day": 1  },  "tag": "customer-123",  "countryOfResidence": "string",  "locale": "en-GB",  "brand": "Acme",  "roles": [    "CARD_ASSIGNEE"  ]}

{
  "name": "Marie",
  "surname": "Laurent",
  "email": "[email protected]",
  "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 userThe individual who creates the customer. For corporates, the root user needs to be a legal representative of the company, such as a director or someone with power of attorney. For consumers, the root user is the customer. Every customer must always have one root user., send a PATCH request to /consumers.
• For corporate root usersRoot userThe individual who creates the customer. For corporates, the root user needs to be a legal representative of the company, such as a director or someone with power of attorney. For consumers, the root user is the customer. Every customer must always have one root user., use /corporates.
• For authorized usersAuthorized UserAn individual that has been invited by the root user to manage a customer's instruments and transactions. They are not the legal owner of the customer but can be granted access to perform operations on its behalf. For corporates, card assignees are created as Authorized Users. US-English variant of _Authorised User_., use /users/${USER_ID}.

For example, to update an authorized userAuthorized UserAn individual that has been invited by the root user to manage a customer's instruments and transactions. They are not the legal owner of the customer but can be granted access to perform operations on its behalf. For corporates, card assignees are created as Authorized Users. US-English variant of _Authorised 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 following GET endpoints return the locale and brand values if they have been set for the user:

• GET /consumers-logged-in consumer
• GET /corporates-logged-in corporate
• GET /users-list authorized usersAuthorized UserAn individual that has been invited by the root user to manage a customer's instruments and transactions. They are not the legal owner of the customer but can be granted access to perform operations on its behalf. For corporates, card assignees are created as Authorized Users. US-English variant of _Authorised User_. for the customer
• GET /users/${USER_ID}-specific authorized userAuthorized UserAn individual that has been invited by the root user to manage a customer's instruments and transactions. They are not the legal owner of the customer but can be granted access to perform operations on its behalf. For corporates, card assignees are created as Authorized Users. US-English variant of _Authorised 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