OTP Consent Requests

This page covers the VIA OTP consent flow for ETK and KVK requests. It explains the flow, the required request fields, and valid and invalid request examples for SMS and email OTP scenarios.

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

Confirm API is used to submit the OTP

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.

Consent requests with OTP

1

Start the Consent Process

The process for obtaining ETK and/or KVKK begins by using the consent method. A consent request is sent to the recipient, which includes:

• "Aydınlatma Metni" and "Onay Metni"

• One-time password (OTP) for verification.

• A requestId, which serves as a reference ID for the operation.

2

Recipient's Response

The recipient grants consent by responding with the OTP to the service provider. This confirms their approval for ETK and/or KVKK.

3

Verification

The confirm method is used to verify the OTP by submitting the recipient's OTP and the associated requestId.

4

Consent Finalization

If the provided OTP matches the one sent to the recipient:

• ETK consent is recorded on behalf of the brand(s).

• KVKK consent is recorded on behalf of the service provider.

5

Netmera Consent Update

After the consent is successfully validated, the recipient's ETK approval, including EMAIL/SMS notification preferences, is saved in the Netmera system.

ETK consent parameters

Parameter	Type	Description	Required
consentTypes	Array of Objects	Includes the consent type details.	Yes
title	String	Type of consent (e.g., ETK).	Yes
types	Array of Strings	Specifies the communication channel(s) through which the approval is requested.["ARAMA"] for phone calls ["MESAJ"] for messages ["ARAMA", "MESAJ"] for both ["EPOSTA"] for email	Yes
recipientType	String	Type of recipient (BIREYSEL or TACIR).	Yes
formId	String	ID of the form sent to the recipient.	Yes
recipient	String	Recipient's phone number or email address.	Yes
verificationType	String	Specifies the approval method (SMS or email OTP). For SMS, it is SMS_OTP, and for email, it is EPOSTA_OTP.	Yes
referenceID	String	This identifier is used to create or update user records in the Netmera system.	Yes

Sample ETK requests

Notes:

• Replace your_rest_api_key with your actual REST API key.

• Ensure formId corresponds to a valid form ID from the IYS Web VIA Management portal.

• Modify recipient with the actual recipient’s email or phone number based on your use case.

ETK request via SMS OTP

curl --location 'https://restapi.netmera.com/via/consent' \
--header 'X-netmera-api-key: your_rest_api_key' \
--header 'Content-Type: application/json' \
--data '{
  "consentTypes": [
    {
      "title": "ETK",
      "types": [
        "MESAJ",
        "ARAMA"
      ],
      "recipientType": "BIREYSEL"
    }
  ],
  "formId": "your_formid",
  "recipient": "+90536.......",
  "verificationType": "SMS_OTP",
  "referenceId": "user1234"
}'

Successful Response (HTTP 200)

{
    "requestId": "requestid"
}

ETK request via email OTP

curl --location 'https://restapi.netmera.com/via/consent' \
--header 'X-netmera-api-key: your_rest_api_key' \
--header 'Content-Type: application/json' \
--data '{
  "consentTypes": [
    {
      "title": "ETK",
      "types": [
        "EMAIL"
      ],
      "recipientType": "BIREYSEL"
    }
  ],
  "formId": "your_formid",
  "recipient": "[e-mail]",
  "verificationType": "EPOSTA_OTP",
  "referenceId": "user1234"
}'

Successful Response (HTTP 200)

{
    "requestId": "requestid"
}

Invalid ETK requests

In case of a failed request, the response will include the following fields:

• message (String): The error message that describes the issue with the request.

• code (String): The error code from the IYS system indicating the specific issue.

• value (String) (This field may return the invalid value depending on the type of error, or it may be omitted): The invalid value that caused the error.

Invalid ETK SMS OTP request

Case: formId does not match the expected type for the given verificationType.

curl --location 'https://restapi.netmera.com/via/consent' \
--header 'X-netmera-api-key: your_rest_api_key' \
--header 'Content-Type: application/json' \
--data '{
    "consentTypes": [
    {
      "title": "ETK",
      "types": [
        "MESAJ"
      ],
      "recipientType": "BIREYSEL"
    }
  ],
  "formId": "your_formid",
  "recipient": "+90536...",
  "verificationType": "SMS_OTP",
  "referenceId": "user1234"
}'

Error Response (HTTP 400)

{
    "message": "The provided verification type (verificationType) does not match the form type. Form type: SHORTURL",
    "code": "H1065"
}

Invalid ETK email OTP request

Case: recipientType is missing in the request body.

curl --location 'https://restapi.netmera.com/via/consent' \
--header 'X-netmera-api-key: your_rest_api_key' \
--header 'Content-Type: application/json' \
--data '{
	 "consentTypes": [
    {
      "title": "ETK",
      "types": [
        "EPOSTA"
      ]
    }
  ],
  "formId": "your_formid",
  "recipient": "[e-mail]",
  "verificationType": "EPOSTA_OTP",
  "referenceId": "user1234"
}'

Error Response (HTTP 400)

{
    "message": "JSON verisinde eksik alanlar: recipientType",
    "code": "H1090"
}

KVK parameters

Field Name	Type	Requirement	Description
consentTypes	Array of Objects	Yes	Contains details about the type of consent requested.
title	String	Yes	Type of form sent to the recipient. For KVK consent, this field must be set as "KVK".
types	Array of Strings	Yes	Consent types for KVK. Possible values: "AYDINLATMA_METNI", "ACIK_RIZA_METNI", "YURTDISI_AKTARIM".
formId	String	Yes	ID of the form sent to the recipient. The corresponding consent form will be sent to the recipient based on this ID. Obtainable via the İYS Web.
verificationType	String	Yes	The method for obtaining consent. "SMS_OTP" for SMS and "EPOSTA_OTP" for email OTP.
recipient	String	Yes	Contact information of the recipient. Either a phone number or email address where the consent request will be sent.
personData	Object	Required for KVK	Contains recipient details if KVK consent requires personal information.
name	String	Required for KVK	Recipient's full name.
recipientIdNumber	String	Required for KVK	Recipient's Turkish ID number.
address	String	Required for KVK	Recipient's address information.

Sample KVK requests

KVK request via SMS OTP

curl --location 'https://restapi.netmera.com/via/consent' \
--header 'X-netmera-api-key: your_rest_api_key' \
--header 'Content-Type: application/json' \
--data '{
  "consentTypes": [
    {
      "title": "KVK",
      "types": [
        "ACIK_RIZA_METNI",
        "YURTDISI_AKTARIM"
      ],
      "personData": {
        "name": "name",
        "recipientIdNumber": "134........",
        "address": "address"
      }
    }
  ],
  "formId": "your_formid",
  "recipient": "+90536.......",
  "verificationType": "SMS_OTP",
  "referenceId": "user1234"
}'

Successful Response (HTTP 200)

{
    "requestId": "requestid"
}

KVK request via email OTP

curl --location 'https://restapi.netmera.com/via/consent' \
--header 'X-netmera-api-key: your_rest_api_key' \
--header 'Content-Type: application/json' \
--data '{
  "consentTypes": [
    {
      "title": "KVK",
      "types": [
        "ACIK_RIZA_METNI",
        "YURTDISI_AKTARIM"
      ],
      "personData": {
        "name": "name",
        "recipientIdNumber": "134........",
        "address": "address"
      }
    }
  ],
  "formId": "your_formid",
  "recipient": "[e-mail]",
  "verificationType": "EPOSTA_OTP",
  "referenceId": "user1234"
}'

Successful Response (HTTP 200):

{
    "requestId": "requestid"
}

Invalid KVK requests

In case of a failed request, the response will include the following fields:

• message (String): The error message that describes the issue with the request.

• code (String): The error code from the IYS system indicating the specific issue.

• value (String) (This field may return the invalid value depending on the type of error, or it may be omitted): The invalid value that caused the error.

Invalid KVK SMS OTP request

Case: The recipientIdNumber field contains an improperly formatted ID number.

curl --location 'https://restapi.netmera.com/via/consent' \
--header 'X-netmera-api-key: your_rest_api_key' \
--header 'Content-Type: application/json' \
--data '{
 "consentTypes": [
    {
      "title": "KVK",
      "types": [
        "ACIK_RIZA_METNI",
        "YURTDISI_AKTARIM"
      ],
      "personData": {
        "name": "name",
        "recipientIdNumber": "134........",
        "address": "address"
      }
    }
  ],
  "formId": "cab8467e-6e58-43d0-abec-2aafc047255d",
  "recipient": "+90536.......",
  "verificationType": "SMS_OTP",
  "referenceId": "user1234"
}'

Error Response (HTTP 400)

{
    "message": "Girdiğiniz TC kimlik numarası: '134........' formata uygun değildir.",
    "code": "H1096"
}

Invalid KVK email OTP request

Case: The title field contains an unexpected value.

curl --location 'https://restapi.netmera.com/via/consent' \
--header 'X-netmera-api-key: your_rest_api_key' \
--header 'Content-Type: application/json' \
--data '{
  "consentTypes": [
    {
      "title": "X",
      "types": [
        "ACIK_RIZA_METNI",
        "YURTDISI_AKTARIM"
      ],
      "personData": {
        "name": "name",
        "recipientIdNumber": "134........",
        "address": "address"
      }
    }
  ],
  "formId": "your_formid",
  "recipient": "[e-mail]",
  "verificationType": "EPOSTA_OTP",
  "referenceId": "user1234"
}'

Error Response (HTTP 400)

{
    "message": "title alanı için gereken değerler: [ETK, KVK, ISG, FATURA, SADAKAT, DIJITAL_FATURA] olmalıdır.",
    "code": "H1013",
    "value": "[X]"
}

Combined ETK and KVK requests

For ETK approval: The request must include the following fields:

1. Verification Method (verificationType)

2. Recipient's Communication Address (recipient)

3. Communication Channel (types)

4. Recipient Type (recipientType)

5. Approval Type (title)

6. Form ID (formId) (The ID of the approval form to be sent to the recipient)

For KVK approval: The request must include the following fields:

1. Verification Method (verificationType)

2. Recipient's Communication Address (recipient)

3. Recipient's Full Name (name)

4. Recipient's National ID Number (recipientIdNumber)

5. Recipient's Address Information (address)

6. Approval Type (title)

7. Form ID (formId) (The ID of the approval form to be sent to the recipient)

ETK and KVK SMS OTP request

curl --location 'https://restapi.netmera.com/via/consent' \
--header 'X-netmera-api-key: your_rest_api_key' \
--header 'Content-Type: application/json' \
--data '{
  "consentTypes": [
	  {
      "title": "ETK",
      "types": [
        "MESAJ",
        "ARAMA"
      ],
      "recipientType": "BIREYSEL"
    },
    {
      "title": "KVK",
      "types": [
        "ACIK_RIZA_METNI",
        "YURTDISI_AKTARIM"
      ],
      "personData": {
        "name": "name",
        "recipientIdNumber": "134........",
        "address": "address"
      }
    }
  ],
  "formId": "your_formid",
  "recipient": "+90536.......",
  "verificationType": "SMS_OTP",
  "referenceId": "user1234"
}'

Successful Response (HTTP 200)

{
    "requestId": "requestid"
}

ETK and KVK email OTP request

curl --location 'https://restapi.netmera.com/via/consent' \
--header 'X-netmera-api-key: your_rest_api_key' \
--header 'Content-Type: application/json' \
--data '{
  "consentTypes": [
	  {
      "title": "ETK",
      "types": [
        "EMAIL"
      ],
      "recipientType": "BIREYSEL"
    },
    {
      "title": "KVK",
      "types": [
        "ACIK_RIZA_METNI",
        "YURTDISI_AKTARIM"
      ],
      "personData": {
        "name": "name",
        "recipientIdNumber": "134........",
        "address": "address"
      }
    }
  ],
  "formId": "your_formid",
  "recipient": "[e-mail]",
  "verificationType": "EPOSTA_OTP",
  "referenceId": "user1234"
}'

Successful Response (HTTP Code: 200)

{
    "requestId": "requestid"
}

Invalid combined requests

In case of a failed request, the response will include the following fields:

• message (String): The error message that describes the issue with the request.

• code (String): The error code from the IYS system indicating the specific issue.

• value (String) (This field may return the invalid value depending on the type of error, or it may be omitted): The invalid value that caused the error.

Invalid ETK and KVK SMS OTP request

Case: personData field is missing.

curl --location 'https://restapi.netmera.com/via/consent' \
--header 'X-netmera-api-key: your_rest_api_key' \
--header 'Content-Type: application/json' \
--data '{
  "consentTypes": [
	  {
      "title": "ETK",
      "types": [
        "MESAJ",
        "ARAMA"
      ],
      "recipientType": "BIREYSEL"
    },
    {
      "title": "KVK",
      "types": [
        "ACIK_RIZA_METNI",
        "YURTDISI_AKTARIM"
      ]
    }
  ],
  "formId": "your_formid",
  "recipient": "+90536.......",
  "verificationType": "SMS_OTP",
  "referenceId": "user1234"
}'

Error Response (HTTP 400)

{
    "message": "JSON verisinde eksik alanlar: personData",
    "code": "H1090"
}

Invalid ETK and KVK email OTP request

Case: types field is missing.

curl --location 'https://restapi.netmera.com/via/consent' \
--header 'X-netmera-api-key: your_rest_api_key' \
--header 'Content-Type: application/json' \
--data '{
  "consentTypes": [
	  {
      "title": "ETK",
      "types": [
        "EMAIL"
      ],
      "recipientType": "BIREYSEL"
    },
    {
      "title": "KVK",
      "personData": {
        "name": "name",
        "recipientIdNumber": "134........",
        "address": "address"
      }
    }
  ],
  "formId": "your_formid",
  "recipient": "[e-mail]",
  "verificationType": "EPOSTA_OTP",
  "referenceId": "user1234"
}'

Error Response (HTTP 400):

{
    "message": "types alanı boş veya null olmamalıdır.",
    "code": "H1057"
}