- 11 Jan 2023
- 5 Minutes To Read
-
Print
-
DarkLight
-
PDF
Client and Group Roles Configuration
- Updated On 11 Jan 2023
- 5 Minutes To Read
-
Print
-
DarkLight
-
PDF
A client models any customer that is just an individual. A group models any customer that is not an individual.
You can specify particular client roles and group roles, which are also referred to as client types and group types. For more information, see Clients and Groups Overview.
With Configuration as Code (CasC), you may batch configure your client and group role configuration via the API using YAML. For general information on CasC, see Configuration as Code Overview.
Although the path for this API is /configuration/clientroles.yaml
, it is used for both client roles and group roles.
Do not confuse group roles in this article with the group roles names that can be assigned to members of a group, found in the Mambu UI under Administration > General Setup > Group Roles.
API Operations
CasC for client roles and group roles supports two operations.
Action | Endpoint | Description |
---|---|---|
GET |
/configuration/clientroles.yaml |
Get current client roles and group roles configuration. |
PUT |
/configuration/clientroles.yaml |
Write a new client roles and group roles configuration to Mambu. |
Parameters
To retrieve only client roles or only group roles when making a GET
request, you may provide the type
parameter with the value CLIENT
or GROUP
.
The type
parameter is not supported for PUT
requests. The API determines whether updates affect clients or groups automatically, based on the contents of the rolesConfiguration
in the configuration.
Note that this has implications for how roles are deleted - for more information, see Deleting client or group roles below.
Managing configuration files
You may manage YAML configuration files in two ways: either include client roles and group roles in a single file, or store them separately in two files, one for group roles and one for client roles.
Requests
For general information on CasC requests such as authentication and required headers, see Configuration as Code Overview.
The following section shows sample requests using curl and basic authentication. For all examples, replace TENANT_NAME
with your actual tenant name.
GET configuration
curl -X GET 'https://TENANT_NAME.mambu.com/api/configuration/clientroles.yaml' \
-H 'Accept: application/vnd.mambu.v2+yaml' \
-H 'Authorization: Basic {auth}'
{auth} is the base-64-encoded value of username:password
. For more information, see Authentication in our API reference.
PUT configuration
curl -X PUT 'https://TENANT_NAME.mambu.com/api/configuration/clientroles.yaml' \
-H 'Accept: application/vnd.mambu.v2+yaml' \
-H 'Content-Type: application/yaml' \
-H 'Authorization: Basic {auth}' \
--data-binary @clientroles.yaml
{auth} is the base-64-encoded value of username:password
. For more information, see Authentication in our API reference.
@clientroles.yaml
represents the absolute path of the file on your device.
Use “--data-raw” if you want to specify the YAML body inline.
Configuration body example
rolesConfiguration:
- type: "CLIENT"
defaultRole:
id: "default_role_id"
name: "default_role_name"
canOpenAccounts: true
canGuarantee: true
requireIdentificationDocuments: false
useDefaultAddress: true
roles:
- id: "id_1"
name: "Name_1"
description: "Desc 1"
idPattern: "@"
canOpenAccounts: false
canGuarantee: false
requireIdentificationDocuments: false
useDefaultAddress: false
- type: "GROUP"
defaultRole:
id: "default_group_role_id"
name: "default_group_role_name"
canOpenAccounts: true
canGuarantee: true
useDefaultAddress: true
roles:
- id: "id_2"
name: "Name_2"
description: "Desc 2"
idPattern: "##"
canOpenAccounts: false
canGuarantee: true
useDefaultAddress: true
- id: "id_3"
name: "Name_3"
description: "Desc 3"
idPattern: "@#"
canOpenAccounts: true
canGuarantee: true
useDefaultAddress: false
rolesConfiguration
attributes
Name | Type | Description | Required |
---|---|---|---|
rolesConfiguration |
List | List of all roles for available account holder types. | ✔ |
type |
String | Defines the role type, it can either be CLIENT or GROUP . |
✔ |
defaultRole |
List | The default role for the given type. | ✔ |
roles |
List | A list of roles for the given type, except the default role. | ✘ |
roles
attributes
Name | Type | Description | Required |
---|---|---|---|
id |
String | The ID used to identify an existing role in the system. If the ID doesn't match an existing role, a new role will be created. | ✔ |
name |
String | The name of the client or group role. | ✔ |
description |
String | The description for the role | ✘ |
idPattern |
String | The ID pattern for the client or group role. | ✘ |
canOpenAccounts |
Boolean | Indicates whether new accounts for this client type can be created. | ✘ |
canGuarantee |
Boolean | Indicates whether the clients under this type can be used as guarantors. | ✘ |
useDefaultAddress |
Boolean | Indicates whether the default address section will be available. | ✘ |
requireIdentificationDocuments |
Boolean | Indicates whether identification documents must be provided for the client to be created. Does not apply for groups. | ✘ |
Deleting client or group roles
When updating client or group roles, any existing client or group role that you do not include in the new configuration will be deleted. Note that you may not delete any client or group role that is currently in use.
Because this endpoint is used to configure both client and group roles, if you entirely omit either role type, then the type you leave out will not be affected. That is, you may update only client roles or only group roles configuration without deleting the other type.
For example, if you update rolesConfiguration
with the type CLIENT
only, then any existing client roles not included in the new configuration will be deleted, but your group roles will not be affected, and no group roles will be deleted.
Replies
If you do not receive a PUT
request until you receive a 200 OK
response.
If you PUT
a valid YAML configuration to the API and you do not receive a 200 OK
status code within 60 seconds, you may receive a 504 Gateway Timeout
status code. We expect all responses to be below 60 seconds.
If you encounter this issue, please contact us through Mambu Support so we can investigate it.
Validations
rolesConfiguration
Name | Validation |
---|---|
rolesConfiguration |
Doesn't accept empty or null elements in the list. |
type |
It can appear only once in the file, all the roles for either CLIENT or GROUP must be defined under the respective configuration. |
defaultRole |
The ID can not be changed. |
roles |
Doesn't accept empty or null elements in the list. It can be empty if there are no roles except for the default role. |
roles
Name | Description |
---|---|
id |
It is unique per role type. Maximum of 32 characters. |
name |
It is unique per role. Maximum of 255 characters. |
description |
Maximum of 256 characters. |
idPattern |
It can contain only alphanumeric characters, '#' numbers, '@' for letters or '$' for letters or numbers. Maximum of 32 characters. |
requireIdentificationDocuments |
It can only be defined for roles with type CLIENT. |
Warnings
If you make an API call and we detect something we need to warn you about then you will receive a list of warnings with a descriptive message for each.
For example, if you attempt to delete a client role that is in use then you will receive the error message ClientRole [CLIENT, id_0] could not be deleted: Client role in use
.