Configurations

For the security, usability and actuality of the investor platform the investor needs to be able to make certain configurations.

We can subdivide these configurations in three different categories:

• Authentication: these configurations regard authentication and account security. These are handled by the identity provider and not by GiroPro.
• Client/appearance: these configurations regard the client of the investor platform. This can be a web- or mobile app. This generally concerns settings like light/dark theme, language, but also a mobile pin and whether or not to use biometrics for authentication. GiroPro does not offer any endpoints for these configurations as they should be stored locally or in the session.
• Personal/communication: these configurations regard information like names of Users, Investors and InvestorAccounts and communication items like e-mail addresses, phone numbers, physical and mailing addresses

We want to focus on the personal and communication configurations as these are the only ones that the GiroPro API offers direct control over.

Users, Investors and InvestorAccounts

To change top-level configurations related to Users, Investors and InvestorAccounts we must use their respective update-endpoints; /UserUpdate, /InvestorUpdate and /v2/InvestorAccountUpdate.

Note that one should only use these endpoints to change the surface-level properties of the relevant items, and use the relevant endpoints for the underlying properties. For example: changing naming-properties like surnames and titles can be done with the /UserUpdate endpoint, but changing the CommunicationItems like addresses should be done through their respective endpoints instead. These endpoints are listed down below.

CommunicationItems

Most configurable information listed under the User, Investor or InvestorAccount are CommunicationItems. These are e-mail addresses, phone numbers and physical and mailing addresses.

BaseCommunicationItem

All of the aforementioned CommunicationItem-types have the same base-class, BaseCommunicationItem, which looks like this:

{
	id: "d290f1ee-6c54-4b01-90e6-d701748f0851", // id of the CommunicationItem
	organizationId: "4563a12a1-a12a-12ab-a123-a12a1a1ab456", // id of the label
	referenceId:"123a12a1-a12a-12ab-a123-a12a1a1ab123", // id of the item it is related to, in this case a user
	referenceType: "User", // options are: Investor, InvestorAccount, User, Label, Client, Giroprovider
	remark: "Mailing address of user", // optional remark related to the item
	communication_type: "AddressItem", // options are: AddressItem, PhoneItem, EmailItem
}

All of the aforementioned CommunicationItem-types have their respective properties on top of the BaseCoummunicationItem properties. These are listed below per type.

AddressItem

In addition to the BaseCommunicationItem properties:

Property	Required	Description	Type and options
type	Yes	Type of address communication item	Options are: postal, invoice, visit
city	Yes	City the address is situated in
postalCode	Yes	Postal code related to the address
street	Yes	Name of the street related to the address
houseNumber	Yes	House number related to the address
country	Yes	Country the address is situated in	max 3 characters [A-Z]{3}
extraAddressLine	No	Extra information about the address like apartment number or number-addition

PhoneItem

In addition to the BaseCommunicationItem properties:

Property	Required	Description	Type and options
type	No	Type of phone communication item	Options are: administration, financial, private, emergency
kind	Yes	Kind of phone connection	Options are: mobile, landline
countryCode	Yes	Country code of the phone number	A ‘+’ and 1 to 5 digits +[1-9]([1-9]?[0-9]?[0-9]?[0-9]?)?
number	Yes	The actual phone number	Digits only

EmailItem

In addition to the BaseCommunicationItem properties:

Property	Required	Description	Type and options
type	No	Type of email communication item	Options are: private, work, financial, invoice
address	Yes	The email address

Retrieving CommunicationItems

CommunicationItems don’t have their own GET endpoints but instead should be retrieved through the relevant User, InvestororInvestorAccount.

POST /CommunicationAdd

We use to /CommunicationAdd endpoint to create a new communication item and connect it to a User, Investor or InvestorAccount.

The endpoint takes a CommunicationAddAggregatedDto as the request body combines the aforementioned properties which makes the request body look like this:

{
	id: "d290f1ee-6c54-4b01-90e6-d701748f0851",
	organizationId: "4563a12a1-a12a-12ab-a123-a12a1a1ab456",
	referenceId:"123a12a1-a12a-12ab-a123-a12a1a1ab123",
	"referenceType": "User", 
	"remark": "Mailing address of user",
	"communication_type": "AddressItem", 
  "country": "NLD",
  "city": "Utrecht",
  "postalCode": "3512NK",
  "street": "Servaasbolwerk",
  "houseNumber": "14",
  "type": "postal"
}

We then use this request body to perform the call:

const url = 'https://api.dev.giropro.pengine.com/PENGINE/Aggregator/SubjectAggregator/CommunicationAdd';
const options = {
  method: 'POST',
  headers: {
    accept: 'application/json', 
    'content-type': 'application/json',
    authorization: 'bearer <token>'
  },
  body: JSON.stringify(<CommunicationAddAggregatedDto>)
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

This call creates a new CommunicationItem and connects it to the specified reference. It is then returned in a PengineResult.

PUT /CommunicationUpdate

We use to /CommunicationUpdate endpoint to change an existing CommunicationItem. The item to change should always first be retrieved from the relevant endpoint.

const url = 'https://api.dev.giropro.pengine.com/PENGINE/Aggregator/SubjectAggregator/CommunicationUpdate';
const options = {
  method: 'POST',
  headers: {
    accept: 'application/json', 
    'content-type': 'application/json',
    authorization: 'bearer <token>'
  },
  body: JSON.stringify(<CommunicationAddAggregatedDto>)
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

This call updates an existing CommunicationItem and then returns in a PengineResult.

DELETE /CommunicationDeleteById/

To remove a CommunicationItem we use the /CommunicationDeleteById/ endpoint. This endpoint takes the labelId and communicationId as path parameters.

const url = 'https://api.dev.giropro.pengine.com/PENGINE/Aggregator/SubjectAggregator/CommunicationDeleteById/<labelId>/<communicationId>';
const options = {
  method: 'DELETE',
  headers: {
    authorization: 'bearer <token>'
  },
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));