During client registration, the user's e-mail address is requested. The e-mail address is unique in our system. Any attempt to register a customer with an existing e-mail address will fail.
There are two options for user registration: client self-registration or administrative client registration.
During self-registration, the user can complete the registration process independently by collecting all the information step by step. This is a three-factor registration for which a GUEST authorization token is required. During this process, the client first receives a code via e-mail, then a code via SMS, and finally a CLIENT token, which is used for all further HTTP calls. This token is valid for one hour.
During initial registration, the client's gender, first name, last name, and e-mail address are requested. In this case, the HTTP proxy may use a GUEST token. As a result, the client receives an e-mail with a code that is used for the second registration.
var clientEmail = $"{Guid.NewGuid().ToString().Replace("-", string.Empty)}@gmail.com";
var clientName = Guid.NewGuid().ToString().Replace("-", string.Empty).Substring(4, 6);
var clientSurname = Guid.NewGuid().ToString().Replace("-", string.Empty).Substring(1, 7);
var gender = await httpClient.GetFromJsonAsync<GenderOutputModel>("/api/v1/genders/code/MALE");
var payload = JsonConvert.SerializeObject(new { GenderId = gender.Id, Name = clientName, Surname = clientSurname, EmailAddress = clientEmail });
var sContent = new StringContent(payload, Encoding.UTF8, "application/json");
var httpResponseMessage = await httpClient.PostAsync("api/v1/users/registration/first-factor", sContent);
var resultAsString = await httpResponseMessage.Content.ReadAsStringAsync();
var firstFactorRegistrationResult = JsonConvert.DeserializeObject<RegistrationFirstFactorOutputModel>(resultAsString);
var clientEmail = UUID.randomUUID().toString() + "@xmail.com";
var clientName = UUID.randomUUID().toString().replace("-", "").substring(4, 6);
var clientSurname = UUID.randomUUID().toString().replace("-", "").substring(1, 7);
// First-factor registration
HttpRequest genderRequest = HttpRequest.newBuilder()
.timeout(Duration.ofMinutes(1))
.uri(URI.create(Program.BASE_URL + "genders/code/MALE"))
.header("Accept-Language", "de-DE")
.header("Authorization", "Bearer " + Program.GUEST_TOKEN)
.header("Content-Type", "application/json")
.build();
HttpResponse response = client.send(genderRequest, BodyHandlers.ofString());
GenderOutputModel genderObj = new Gson().fromJson(response.body().toString(), GenderOutputModel.class);
var genderId = genderObj.Id;
var firstFactorPayload = "{'GenderId':" + genderId + ",'Name':'" + clientName + "','Surname':'" + clientSurname + "', 'EmailAddress': '" + clientEmail + "'}";
HttpRequest firstFactorRequest = HttpRequest.newBuilder()
.timeout(Duration.ofMinutes(1))
.uri(URI.create(Program.BASE_URL + "users/registration/first-factor"))
.header("Accept-Language", "de-DE")
.header("Authorization", "Bearer " + Program.GUEST_TOKEN)
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(firstFactorPayload))
.build();
response = client.send(firstFactorRequest, BodyHandlers.ofString());
RegistrationFirstFactorOutputModel fistFactorRegistrationResult = new Gson().fromJson(response.body().toString(), RegistrationFirstFactorOutputModel.class);
At this stage, the client enters the code received by e-mail and the mobile phone:
payload = JsonConvert.SerializeObject(new { PhoneNumberPrefix = "0041", PhoneNumberNumber = "767676000" });
sContent = new StringContent(payload, Encoding.UTF8, "application/json");
httpResponseMessage = await httpClient.PostAsync("api/v1/users/registration/second-factor", sContent);
resultAsString = await httpResponseMessage.Content.ReadAsStringAsync();
var secondFactorRegistrationResult = JsonConvert.DeserializeObject<RegistrationSecondFactorOutputModel>(resultAsString);
// Second-factor registration
var secondFactorPayload = "{'PhoneNumberPrefix': '0041','PhoneNumberNumber':'767965454'}";
HttpRequest secondFactorRequest = HttpRequest.newBuilder()
.timeout(Duration.ofMinutes(1))
.uri(URI.create(Program.BASE_URL + "users/registration/second-factor"))
.header("Accept-Language", "de-DE")
.header("Authorization", "Bearer " + Program.GUEST_TOKEN)
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(secondFactorPayload))
.build();
response = client.send(secondFactorRequest, BodyHandlers.ofString());
RegistrationSecondFactorOutputModel registrationSecondFactorOutputModel = new Gson().fromJson(response.body().toString(), RegistrationSecondFactorOutputModel.class);
This step completes the registration process. The response contains a CLIENT token that must be used for subsequent HTTP calls:
var language = await httpClient.GetFromJsonAsync<LanguageOutputModel>("/api/v1/languages/code/DE");
var legalAcceptance = await httpClient.GetFromJsonAsync<LegalAcceptanceOutputModel>("/api/v1/legal-acceptances/active");
payload = JsonConvert.SerializeObject(new
{
ManagementPersonalDataConsent = DateTime.Now,
SmsToken = secondFactorRegistrationResult.Token,
EmailToken = firstFactorRegistrationResult.Token,
GenderId = gender.Id,
Name = clientName,
Surname = clientSurname,
EmailAddress = clientEmail,
PhoneNumberPrefix = "0041",
PhoneNumberNumber = "767676000",
Password = "Ast@LaVist@!",
LanguageId = language.Id,
LegalAcceptanceId = legalAcceptance.Id,
});
sContent = new StringContent(payload, Encoding.UTF8, "application/json");
httpResponseMessage = await httpClient.PostAsync("api/v1/users/registration/third-factor", sContent);
resultAsString = await httpResponseMessage.Content.ReadAsStringAsync();
var thirdFactorRegistrationResult = JsonConvert.DeserializeObject<RegistrationThirdFactorOutputModel>(resultAsString);
// Third-factor registration
HttpRequest languageRequest = HttpRequest.newBuilder()
.timeout(Duration.ofMinutes(1))
.uri(URI.create(Program.BASE_URL + "languages/code/DE"))
.header("Accept-Language", "de-DE")
.header("Authorization", "Bearer " + Program.GUEST_TOKEN)
.header("Content-Type", "application/json")
.build();
response = client.send(languageRequest, BodyHandlers.ofString());
LanguageOutputModel languageObj = new Gson().fromJson(response.body().toString(), LanguageOutputModel.class);
var languageId = languageObj.Id;
HttpRequest legalAcceptanceRequest = HttpRequest.newBuilder()
.timeout(Duration.ofMinutes(1))
.uri(URI.create(Program.BASE_URL + "legal-acceptances/active"))
.header("Accept-Language", "de-DE")
.header("Authorization", "Bearer " + Program.GUEST_TOKEN)
.header("Content-Type", "application/json")
.build();
response = client.send(legalAcceptanceRequest, BodyHandlers.ofString());
LegalAcceptanceOutputModel legalAcceptanceObj = new Gson().fromJson(response.body().toString(), LegalAcceptanceOutputModel.class);
var legalAcceptanceId = legalAcceptanceObj.Id;
StringBuilder thirdFactorPayload = new StringBuilder("{");
thirdFactorPayload.append("'ManagementPersonalDataConsent': '2025-01-01',");
thirdFactorPayload.append("'SmsToken': '" + registrationSecondFactorOutputModel.Token + "',");
thirdFactorPayload.append("'EmailToken': '" + fistFactorRegistrationResult.Token + "',");
thirdFactorPayload.append("'GenderId': " + genderId + ",");
thirdFactorPayload.append("'Name': '" + clientName + "',");
thirdFactorPayload.append("'Surname': '" + clientSurname + "',");
thirdFactorPayload.append("'EmailAddress': '" + clientEmail + "',");
thirdFactorPayload.append("'PhoneNumberPrefix': '0041',");
thirdFactorPayload.append("'PhoneNumberNumber': '767965454',");
thirdFactorPayload.append("'Password': 'AstaLaVista!',");
thirdFactorPayload.append("'LanguageId': " + languageId + ",");
thirdFactorPayload.append("'LegalAcceptanceId': " + legalAcceptanceId);
thirdFactorPayload.append("}");
HttpRequest thirdFactorRequest = HttpRequest.newBuilder()
.timeout(Duration.ofMinutes(1))
.uri(URI.create(Program.BASE_URL + "users/registration/third-factor"))
.header("Accept-Language", "de-DE")
.header("Authorization", "Bearer " + Program.GUEST_TOKEN)
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(thirdFactorPayload.toString()))
.build();
response = client.send(thirdFactorRequest, BodyHandlers.ofString());
RegistrationThirdFactorOutputModel registrationThirdFactorOutputModelObj = new Gson().fromJson(response.body().toString(), RegistrationThirdFactorOutputModel.class);
System.out.println("User ID = " + registrationThirdFactorOutputModelObj.UserId);
The CLIENT token is valid for 60 minutes/one hour. Once this period has expired, a new CLIENT token can be obtained by following the refreshing token procedure.
Administrative client registration is used to register a client in one call and request an ADMIN token. This method is the best option for software-to-software/server-to-server registration of a client. It requires an ADMIN token, which usually has a long lifespan (1-10 years). Please keep it secret.
The following example shows how to register a client and all its data in a single call. In this case, the HTTP proxy must use an ADMIN token.
var language = await httpClient.GetFromJsonAsync<LanguageOutputModel>("/api/v1/languages/code/DE");
var legalAcceptance = await httpClient.GetFromJsonAsync<LegalAcceptanceOutputModel>("/api/v1/legal-acceptances/active");
var nationality = await httpClient.GetFromJsonAsync<NationalityOutputModel>("api/v1/nationalities/code/CH");
var country = await httpClient.GetFromJsonAsync<CountryOutputModel>("api/v1/countries/code/CH");
var pensionSituation = await httpClient.GetFromJsonAsync<PensionSituationOutputModel>("api/v1/pension-situations/code/PENSION-FUND");
var taxLiability = await httpClient.GetFromJsonAsync<TaxLiabilityOutputModel>("api/v1/tax-liabilities/code/CH");
var civilStatus = await httpClient.GetFromJsonAsync<CivilStatusOutputModel>("api/v1/civil-statuses/code/SINGLE");
var gender = await httpClient.GetFromJsonAsync<GenderOutputModel>("/api/v1/genders/code/MALE");
var payload = JsonConvert.SerializeObject(new
{
ManagementPersonalDataConsent = DateTime.Now,
Name = clientName,
Surname = clientSurname,
Email = clientEmail,
PhoneNumberPrefix = "0041",
PhoneNumberNumber = "767965365",
PensionSituationId = pensionSituation.Id,
LanguageId = language.Id,
LegalAcceptanceId = legalAcceptance.Id,
Address = new
{
City = "Baar",
Zip = "6340",
Street = "Neugasse",
StreetNr = "28A",
CountryId = country.Id,
CoName = "Zoo",
CoSurname = "Zurich"
},
TaxLiabilityId = taxLiability.Id,
GenderId = gender.Id,
Nationality1Id = nationality.Id,
BirthDate = DateTime.Now.AddYears(-23)
});
var httpResponseMessage = await httpClient.PostAsync("api/v1/users", new StringContent(payload, Encoding.UTF8, "application/json"));
var userId = UriHelper.GetIdFromLocationUri(httpResponseMessage.Headers.Location);
var clientEmail = UUID.randomUUID().toString() + "@mail.com";
var clientName = UUID.randomUUID().toString().replace("-", "").substring(4, 6);
var clientSurname = UUID.randomUUID().toString().replace("-", "").substring(1, 7);
HttpRequest languageRequest = HttpRequest.newBuilder()
.timeout(Duration.ofMinutes(1))
.uri(URI.create(Program.BASE_URL + "languages/code/FR"))
.header("Accept-Language", "de-DE")
.header("Authorization", "Bearer " + Program.GUEST_TOKEN)
.header("Content-Type", "application/json")
.build();
var response = client.send(languageRequest, BodyHandlers.ofString());
LanguageOutputModel languageObj = new Gson().fromJson(response.body().toString(), LanguageOutputModel.class);
var languageId = languageObj.Id;
HttpRequest legalAcceptanceRequest = HttpRequest.newBuilder()
.timeout(Duration.ofMinutes(1))
.uri(URI.create(Program.BASE_URL + "legal-acceptances/active"))
.header("Accept-Language", "de-DE")
.header("Authorization", "Bearer " + Program.GUEST_TOKEN)
.header("Content-Type", "application/json")
.build();
response = client.send(legalAcceptanceRequest, BodyHandlers.ofString());
LegalAcceptanceOutputModel legalAcceptanceObj = new Gson().fromJson(response.body().toString(), LegalAcceptanceOutputModel.class);
var legalAcceptanceId = legalAcceptanceObj.Id;
HttpRequest nationalityRequest = HttpRequest.newBuilder()
.timeout(Duration.ofMinutes(1))
.uri(URI.create(Program.BASE_URL + "nationalities/code/CH"))
.header("Accept-Language", "de-DE")
.header("Authorization", "Bearer " + Program.GUEST_TOKEN)
.header("Content-Type", "application/json")
.build();
response = client.send(nationalityRequest, BodyHandlers.ofString());
NationalityOutputModel nationalityObj = new Gson().fromJson(response.body().toString(), NationalityOutputModel.class);
var nationalityId = nationalityObj.Id;
HttpRequest countryRequest = HttpRequest.newBuilder()
.timeout(Duration.ofMinutes(1))
.uri(URI.create(Program.BASE_URL + "countries/code/CH"))
.header("Accept-Language", "de-DE")
.header("Authorization", "Bearer " + Program.GUEST_TOKEN)
.header("Content-Type", "application/json")
.build();
response = client.send(countryRequest, BodyHandlers.ofString());
CountryOutputModel countryObj = new Gson().fromJson(response.body().toString(), CountryOutputModel.class);
var countryId = countryObj.Id;
HttpRequest pensionRequest = HttpRequest.newBuilder()
.timeout(Duration.ofMinutes(1))
.uri(URI.create(Program.BASE_URL + "pension-situations/code/PENSION-FUND"))
.header("Accept-Language", "de-DE")
.header("Authorization", "Bearer " + Program.GUEST_TOKEN)
.header("Content-Type", "application/json")
.build();
response = client.send(pensionRequest, BodyHandlers.ofString());
PensionSituationOutputModel pensionObj = new Gson().fromJson(response.body().toString(), PensionSituationOutputModel.class);
var pensionId = pensionObj.Id;
HttpRequest taxLiabilityRequest = HttpRequest.newBuilder()
.timeout(Duration.ofMinutes(1))
.uri(URI.create(Program.BASE_URL + "tax-liabilities/code/CH"))
.header("Accept-Language", "de-DE")
.header("Authorization", "Bearer " + Program.GUEST_TOKEN)
.header("Content-Type", "application/json")
.build();
response = client.send(taxLiabilityRequest, BodyHandlers.ofString());
TaxLiabilityOutputModel taxLiabilityObj = new Gson().fromJson(response.body().toString(), TaxLiabilityOutputModel.class);
var taxLiabilityId = taxLiabilityObj.Id;
HttpRequest civilStatusRequest = HttpRequest.newBuilder()
.timeout(Duration.ofMinutes(1))
.uri(URI.create(Program.BASE_URL + "civil-statuses/code/SINGLE"))
.header("Accept-Language", "de-DE")
.header("Authorization", "Bearer " + Program.GUEST_TOKEN)
.header("Content-Type", "application/json")
.build();
response = client.send(civilStatusRequest, BodyHandlers.ofString());
CivilStatusOutputModel civilStatusObj = new Gson().fromJson(response.body().toString(), CivilStatusOutputModel.class);
var civilStatusId = civilStatusObj.Id;
HttpRequest genderRequest = HttpRequest.newBuilder()
.timeout(Duration.ofMinutes(1))
.uri(URI.create(Program.BASE_URL + "genders/code/MALE"))
.header("Accept-Language", "de-DE")
.header("Authorization", "Bearer " + Program.GUEST_TOKEN)
.header("Content-Type", "application/json")
.build();
response = client.send(genderRequest, BodyHandlers.ofString());
GenderOutputModel genderObj = new Gson().fromJson(response.body().toString(), GenderOutputModel.class);
var genderId = genderObj.Id;
// Preparing payload
StringBuilder registrationPayload = new StringBuilder("{");
registrationPayload.append("'ManagementPersonalDataConsent': '2025-01-01',");
registrationPayload.append("'CivilStatusId': " + civilStatusId + ",");
registrationPayload.append("'Name': '" + clientName + "',");
registrationPayload.append("'Surname': '" + clientSurname + "',");
registrationPayload.append("'Email': '" + clientEmail + "',");
registrationPayload.append("'PhoneNumberPrefix': '0041',");
registrationPayload.append("'PhoneNumberNumber': '767965454',");
registrationPayload.append("'PensionSituationId': '" + pensionId + "',");
registrationPayload.append("'LanguageId': " + languageId + ",");
registrationPayload.append("'LegalAcceptanceId':" + legalAcceptanceId + ",");
registrationPayload.append("'Address': {");
registrationPayload.append(" 'City': 'Baar',");
registrationPayload.append(" 'Zip': 6340,");
registrationPayload.append(" 'Street': 'Nowhere',");
registrationPayload.append(" 'StreetNr': '1',");
registrationPayload.append(" 'CountryId': " + countryId + ",");
registrationPayload.append("},");
registrationPayload.append("'GenderId': " + genderId + ",");
registrationPayload.append("'BirthDate': '2006-01-01',");
registrationPayload.append("'Nationality1Id': " + nationalityId + ",");
registrationPayload.append("'TaxLiabilityId': " + taxLiabilityId);
registrationPayload.append("}");
HttpRequest createRequest = HttpRequest.newBuilder()
.timeout(Duration.ofMinutes(1))
.uri(URI.create(Program.BASE_URL + "users"))
.header("Accept-Language", "de-DE")
.header("Authorization", "Bearer " + Program.ADMIN_TOKEN)
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(registrationPayload.toString()))
.build();
response = client.send(createRequest, BodyHandlers.ofString());
ClientOutputModel clientObj = new Gson().fromJson(response.body().toString(), ClientOutputModel.class);
System.out.println("User ID = " + clientObj.Id);