Client and Group Roles Configuration

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.

note

Although the path for this API is /configuration/clientroles.yaml, it is used for both client roles and group roles.

warning

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

Please Note

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.

API Operations​

Parameters​

Managing configuration files​

Requests​

GET configuration​

PUT configuration​

Configuration body example​

rolesConfiguration attributes​

roles attributes​

Deleting client or group roles​

Replies​

Validations​

rolesConfiguration​

roles​

Warnings​