VIA Integration

VIA is a communication management system for SMS and email permission management. This page covers VIA setup in Netmera, the available consent flows, the request parameters, and how referenceId affects user creation and updates. For more details about VIA, visit the VIA website.

Configure VIA in Netmera Panel

1. Navigate to Netmera Panel > Connectors > Installed > IYS.

2. Set the correct IYS configuration:

   • Fill in the Brand and IYS Codes fields with the values obtained from IYS.

3. Enable the VIA feature by selecting the Via Enabled checkbox.

Connectors

Incorrect configuration

If the configuration is incorrect or the checkbox is not enabled, REST service responses will return with the following errors:

Error Code: 400 - Bad Request

validationError: IYS config is invalid for appKey
validationError: Via service is inactive for appKey

SMS and email permission management

You can obtain user consent or decline for SMS and email preferences in two ways when using VIA integration:

1. Consent Management via Short URL

• Use the form created in the IYS panel to send a short URL to users, allowing them to manage their SMS or email preferences.

2. Consent Management via One-Time Password (OTP)

• Use the form created in the IYS panel to send an OTP to users, enabling them to confirm their SMS or email preferences.

IYS form requirements

Create Separate Forms

While you can obtain SMS and email permissions simultaneously through the same OTP or short URL, forms for Short URL and OTP Consent must be created independently. A single combined form that includes both Short URL and OTP is not permitted.

Use the IYS Panel for Form Generation

Forms must be generated directly through the IYS panel. Netmera does not support form creation, as this process is exclusively managed by IYS.

Short URL consent flow

For a full version, please see the board here.

1

Prepare the Short URL consent form

Prepare a Short URL consent form using your IYS Panel. Once the form is ready, submit it to IYS for approval.

2

Obtain IYS Approval

After IYS approves the form, it will be available for use in API calls. The form ID provided by IYS will serve as the formId value in your requests.

3

Send the Consent Form to the User

Send the consent form link to your users via email or SMS. Use the API endpoint https://restapi.netmera.com/via/consent to share the link with your users.

4

User Submits Their Consent

When the user receives the link, they can open the form, select their SMS or email permissions, and submit their approval.

5

Confirmation Information Sent to the User

After the user submits their consent, they will receive a confirmation via email or SMS informing them of the permissions they selected and their submission status.

6

Consent Data Saved in Netmera

Netmera saves the user permissions in the Netmera Panel. This synchronization occurs every 10 minutes to ensure the latest user preferences are reflected.

OTP consent flow

For the full version, see the board here.

1

Prepare the OTP consent form

Create an OTP consent form using your IYS Panel. Once the form is ready, submit it to IYS for approval.

2

Obtain IYS Approval

After IYS approves the form, it will be ready for use in API calls. The form ID provided by IYS will serve as the formId value in your requests.

3

Send the Consent Form to the User

Send an email or SMS to the user containing the OTP code. Use the API endpoint https://restapi.netmera.com/via/consent to share the code with the user.

4

User Submits Their Consent

The user enters the OTP code they received. Use the API endpoint https://restapi.netmera.com/via/confirm to submit the OTP.

5

Confirmation Information Sent to the User

The user will receive a confirmation via email or SMS, detailing the permissions they selected and the status of their submission.

6

Consent Data Saved in Netmera

Netmera automatically saves the user’s permissions in the Netmera Panel. Synchronization occurs every 10 minutes to ensure the latest user preferences are reflected.

VIA consent API parameters

Before you start

• referenceId is required in every request.

• formId must come from the VIA Management interface.

• recipient must be an email address or an MSISDN in +90... format.

• name, recipientIdNumber, address, and personData are required only for KVKK requests.

Base request fields

Field	Required	Description
title	Yes	Specifies the consent type to request. Use ETK for ETK consent requests.
types	Yes	Specifies the channel or consent type to request.
recipientType	Yes	Specifies the recipient type: BİREYSEL or TACIR.
formId	Yes	ID of the consent form to send. Get this value from the VIA Management interface.
recipient	Yes	Recipient phone number in +90... format or recipient email address.
verificationType	Yes	Specifies the consent method to use for the request.
referenceId	Yes	Unique identifier used to create or update user records in Netmera.

Allowed values

Field	Context	Description
types	ETK	"ARAMA", "MESAJ", ["ARAMA", "MESAJ"], ["MESAJ", "ARAMA"], "EPOSTA"
types	KVKK	"AYDINLATMA_METNI", "ACIK_RIZA_METNI", "YURTDISI_AKTARIM"
verificationType	Consent request	"SMS_OTP", "EPOSTA_OTP", "EPOSTA_SHORTURL", "SMS_SHORTURL", "EPOSTA_APPROVALURL"

KVKK-only fields

Field	Required	Description
name	Required for KVKK	Recipient’s first and last name.
recipientIdNumber	Required for KVKK	Recipient’s Turkish Identity Number.
address	Required for KVKK	Recipient address details.
personData	Required for KVKK	Object that contains name and recipientIdNumber.

Response body fields

HTTP Code	Field	Description
200	requestId	Returned when the consent request is created successfully. Use it to check request status or confirm an OTP flow.
400	message	Returned when the request fails validation.
	code	Returned for IYS-side validation errors.
	value	Returned when the failing input value is available.
500	message	Returned when the server cannot parse the request data.

User update or create with referenceId

referenceId is a required field. It uniquely identifies the user in Netmera and determines whether Netmera updates an existing user or creates a new one.

If referenceId is not provided

If referenceId is missing from the request, the system returns 400 Bad Request with the message “ReferenceID is empty”.

{
  "message": "referenceId is empty",
  "status": 400
}

How Netmera matches a user

1

Check email

Netmera first looks up the user by email address without using referenceId.

If a matching user exists, Netmera updates the user’s consent status based on the VIA response. For example, the status can change to “Onay verildi” or “Onay verilmedi”.

2

Check MSISDN

If no user is found by email, Netmera looks up the user by MSISDN.

3

Check referenceId

If no user is found by MSISDN, Netmera looks up the user by referenceId.

If referenceId exists, the user was likely created earlier through the VIA channel. Netmera then updates the user’s MSISDN and consent status.

4

Create or update the user

If Netmera still does not find a matching user, it creates a new user with the available identifier values.

If no user exists for referenceId

If Netmera does not find a user for the given referenceId, it creates a new user with the available permission identifier.

• If only email is provided, Netmera creates a user with email and sets MSISDN to false.

• If only MSISDN is provided, Netmera creates a user with MSISDN and sets email to false.

• If both are provided, Netmera creates one user with both identifiers.

• Netmera stores referenceId as a profile attribute.

For example, if Netmera finds no email match, no MSISDN match, and no referenceId match, it creates a new user. If the request includes both email and MSISDN, the new user stores both identifiers.

Why separate users can appear

Netmera can create separate email and MSISDN users when no shared referenceId exists yet. Later requests can merge them when both identifiers can be linked to the same user.

User creation scenarios

Scenario	Result
User does not exist as an email user and grants email permission.	Netmera creates a new email user.
User does not exist as an MSISDN user and grants MSISDN permission.	Netmera creates a new MSISDN user.
User already exists as an email user and grants only MSISDN permission.	Netmera creates a new MSISDN user. Since there is no referenceId match yet, Netmera cannot link both identifiers to the same user. If email permission is granted later, the users can merge.
User already exists as an MSISDN user and grants only email permission.	Netmera creates a new email user. Since there is no referenceId match yet, Netmera cannot link both identifiers to the same user. If MSISDN permission is granted later, the users can merge.
User does not already exist as an email or MSISDN user and grants both permissions.	Netmera creates one user with both identifiers.
User already exists as an email user but not as an MSISDN user, and both permissions are granted.	Netmera merges the user into a single record when the MSISDN request arrives first. The existing email user is not duplicated.
User already exists as an email user and grants only email permission.	Netmera updates the existing email user instead of creating a new one.
User already exists as an MSISDN user and grants only MSISDN permission.	Netmera updates the existing MSISDN user instead of creating a new one.