CDP - Documentation

CDP API

Participations

You can use this API to add and remove users from the campaign. All receipts and voucher codes for a user must always be sent in full.

Property	Description
`customer_phone`	(required) String must start with "+" and can only contain numbers and plus signs.
`receipts`	(optional) Array, All receipts belonging to the customer.
`gifts`	(optional) Array, All coupons/gifts belonging to the customer.
`- coupon_code`	A string representing the coupon code.
`- gift_description`	A string representing the gift description.
`- given_date`	A timestamp indicating the date when the gift was given to the customer.

NOTE: To avoid synchronization problems, all receipts and coupons for the customer must be added each time. If these fields are not submitted, or are submitted empty, all receipts for that customer will be deleted. To delete a specific receipt or coupon for a customer, simply skip the data for that item.

POST

/ext/third-party-campaign/:campaignId/participants

Example request body

[
  {
    "customer_phone": "+905555555555",
    "receipts": [
      {
        "receipt_no": "1AnW",
        "receipt_store_id": "NJ8GHxQZae",
        "receipt_store_name": "3M Migros",
        "receipt_amount": 10,
        "receipt_date": 1680779303642
      }
    ],
    "gifts": [
      {
        "coupon_code": "Code",
        "given_date": 1680537756951
      }
    ]
  }
]

Example response

{
  "referenceId": "5ebde3f5-3022-4e0e-81d6-048b530415a0",
  "source": "PROVIDER",
  "status": 2,
  "time": "2023-05-22T12:43:04.738Z"
}

Report

Returns the last status information of the campaign participants in the queue and any errors.

Property	Description
`referenceId`	(required) Reference info used to track the data in the queue.

Status Codes

Code	Description
`0`	Error, data is not in proper format or incorrect.
`1`	Successful.
`2`	Added to the queue, waiting.

GET

/ext/third-party-campaign/:referenceId/report

Example request body

/ext/third-party-campaign/5ebde3f5-3022-4e0e-81d6-048b530415a0/report

Example response

{
  "_id": "646b63588b8b34dbe3f1a0b0",
  "referenceId": "5ebde3f5-3022-4e0e-81d6-048b530415a0",
  "source": "PROVIDER",
  "status": 2,
  "error": [],
  "createdAt": "2023-05-22T12:43:04.738Z",
  "updatedAt": "2023-05-22T12:43:04.738Z"
}

Create or Update Customer (v2)

This endpoint is used for updating existing customers or creating new customers.

This endpoint requires a Bearer token issued for one of the wifi, Lucy or insider access cards.

Either customer_phone or customer_email must be provided. The customer is looked up by phone number first; if no phone number is sent, the lookup falls back to email.

Property	Description
`customer_phone`	(required if no email) String, 10-16 characters. Must include the country code; the leading `+` is optional: `905395555555` and `+905395555555` are accepted. Local formats without a country code (`05395555555`, `5395555555`) are rejected. Numbers from all countries are supported. The number is normalized to E.164 (`+90...`) and must be a valid mobile number.
`customer_email`	(required if no phone) String, a valid email address. Stored lowercased.
`customer_name`	(required for new customers) String, 2-64 characters, customer's first name.
`customer_surname`	(required for new customers) String, 2-64 characters, customer's last name.
`customer_gender`	(required for new customers) String, one of `male`, `female`, `unknown`.
`customer_birthdate`	(required for new customers) String, in `YYYY-MM-DD` format.
`customer_country`	(optional) String, ISO 3166-1 alpha-2 country code (`TR`, `DE`, ...).
`customer_province`	(optional) String, province (İl). Validated against the known province list.
`customer_district`	(optional) String, district (İlçe). Must belong to the given province.
`customer_locality`	(optional) String, locality (Mahalle).
`customer_address`	(optional) String, street address.
`customer_accepts_kvkk`	(required for new customers) Boolean, must be `true`. KVKK (data protection) acceptance.
`customer_accepts_kvkk_at`	(required with `customer_accepts_kvkk`) Number, millisecond timestamp of KVKK acceptance.
`customer_allows_sms`	(optional) Boolean, opt-in status for SMS messages.
`customer_allows_sms_at`	(required with `customer_allows_sms`) Number, millisecond timestamp of the SMS consent.
`customer_allows_call`	(optional) Boolean, opt-in status for phone calls.
`customer_allows_call_at`	(required with `customer_allows_call`) Number, millisecond timestamp of the call consent.
`customer_allows_email`	(optional) Boolean, opt-in status for email.
`customer_allows_email_at`	(required with `customer_allows_email`) Number, millisecond timestamp of the email consent.
`customer_cks`	(optional) String.

Consent freshness: a consent field is only updated when its value differs from the stored one and its *_at timestamp is newer than the timestamp stored in CDP. Stale consents are silently ignored, so late-delivered batches cannot overwrite fresher data.
Three business days rule: consent timestamps must be within the last three business days, otherwise the request is rejected with 400.
Duplicate protection: an email address that is already registered to a different customer is rejected with 400. New customers are created atomically by phone/email, so concurrent requests for the same person cannot create duplicate records.
Soft-deleted customers: if the customer was deleted, the request is accepted only when it carries at least one consent newer than the deletion; the customer is then reactivated. Otherwise the request is rejected with 400.
Consent authority (IYS): consent changes are forwarded to IYS before the customer is persisted. If this step fails, nothing is saved and a generic 500 is returned; retry the request later.
If customer_allows_sms, customer_allows_call, customer_allows_email are not sent for a new customer, they default to false.

NOTE: customer_phone in the response is always returned in E.164 format (+90...), regardless of the format it was sent in.

Business-rule violations return 400 with the following body shape:

Status	Error message	When
`400`	`Phone number or email address is required.`	Neither `customer_phone` nor `customer_email` was sent.
`400`	`Phone number must be in the format [+][country code][area code][phone number]`	The phone number could not be parsed, is missing the country code, or is not a valid number.
`400`	`Must have mobile phone number`	The phone number is valid but not a mobile number.
`400`	`You must enter a valid email address`	The email address is malformed.
`400`	`Email address is already registered to another customer.`	The email belongs to a different customer record.
`400`	`Permissions must be within the last three business days: {consents}`	One or more consent timestamps are older than three business days.
`400`	`You cannot perform this action because the customer has been deleted.`	The customer was deleted and the request carries no newer consent.
`400`	`The following fields are required to create a user: {fields}`	A new customer is being created and required fields are missing.
`400`	`Invalid city name: {value}` / `Invalid town name: {value}` / city-town relation errors	`customer_province` / `customer_district` failed locality validation.
`403`	`Forbidden`	Missing, malformed or unauthorized Bearer token.
`422`	Schema validation message	The request body does not match the schema (wrong types, length limits, missing `*_at` fields, etc.).
`500`	`An internal server error occurred`	Consents could not be delivered to the consent authority; nothing was saved. Retry later.

403 and 422 responses use the standard error envelope:

BREAKING CHANGE: POST /ext/customers/upsert has been removed. Use POST /ext/customers/upsert-v2 instead. The v2 endpoint validates and normalizes phone numbers, protects against duplicate customer records, and wraps the response in a { "status": true, "customer": { ... } } envelope.

POST

/ext/customers/upsert-v2

Authentication

curl --location 'https://api.kns-cdp.com/ext/customers/upsert-v2' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --data-raw '{
    "customer_phone": "+905395555555",
    "customer_email": "fatih.akdogan@kns.com.tr",
    "customer_name": "Fatih",
    "customer_surname": "Akdoğan",
    "customer_gender": "male",
    "customer_birthdate": "1997-06-11",
    "customer_country": "TR",
    "customer_province": "İstanbul",
    "customer_district": "Sarıyer",
    "customer_locality": "Reşitpaşa Mahallesi",
    "customer_address": "Prof. B. Karafakıoğlu Cd No:116",
    "customer_accepts_kvkk": true,
    "customer_accepts_kvkk_at": 1782813645498,
    "customer_allows_sms": true,
    "customer_allows_sms_at": 1782813645498,
    "customer_allows_call": true,
    "customer_allows_call_at": 1782813645498,
    "customer_allows_email": false,
    "customer_allows_email_at": 1782813645498
  }'

Example request body

{
  "customer_phone": "+905395555555",
  "customer_email": "fatih.akdogan@kns.com.tr",
  "customer_name": "Fatih",
  "customer_surname": "Akdoğan",
  "customer_gender": "male",
  "customer_birthdate": "1997-06-11",
  "customer_country": "TR",
  "customer_province": "İstanbul",
  "customer_district": "Sarıyer",
  "customer_locality": "Reşitpaşa Mahallesi",
  "customer_address": "Prof. B. Karafakıoğlu Cd No:116",
  "customer_accepts_kvkk": true,
  "customer_accepts_kvkk_at": 1782813645498,
  "customer_allows_sms": true,
  "customer_allows_sms_at": 1782813645498,
  "customer_allows_call": true,
  "customer_allows_call_at": 1782813645498,
  "customer_allows_email": false,
  "customer_allows_email_at": 1782813645498
}

Behavior notes

Example response

{
  "status": true,
  "customer": {
    "_id": "644231fe0ff5b6105966b383",
    "customer_phone": "+905395555555",
    "customer_name": "Fatih",
    "customer_surname": "Akdoğan",
    "customer_gender": "male",
    "customer_email": "fatih.akdogan@kns.com.tr",
    "customer_birthdate": "1997-06-11",
    "customer_profile_photo": "",
    "customer_province": "İstanbul",
    "customer_district": "Sarıyer",
    "customer_locality": "Reşitpaşa Mahallesi",
    "customer_address": "Prof. B. Karafakıoğlu Cd No:116",
    "customer_accepts_kvkk": true,
    "customer_accepts_terms_conditions": false,
    "customer_allows_sms": true,
    "customer_allows_call": true,
    "customer_allows_email": false,
    "customer_is_parent": false,
    "customer_is_developer": false,
    "customer_cks": "",
    "customer_vehicle_plate": ""
  }
}

Error responses

{
  "status": false,
  "errors": ["Email address is already registered to another customer."]
}

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Forbidden"
}

Create or Update Customer (DEPRECATED)

This endpoint has been removed and no longer accepts requests.

POST

/ext/customers/upsert

DEPRECATED: POST /ext/customers/upsert has been removed. Use POST /ext/customers/upsert-v2 instead.

Check Customer KVKK and ETK Status

This endpoint is used to check a customer's KVKK acceptance and ETK (electronic communication) permissions by phone number. It returns the customer's name, surname, KVKK acceptance status, and ETK permissions.

This endpoint requires authentication with the insider access card bearer token.

Property	Description
`customer_phone`	(required) String must start with "+" and can only contain numbers and plus signs.

Property	Description
`customer_name`	String, customer's first name
`customer_surname`	String, customer's last name
`customer_phone`	String, customer's phone number
`customer_accepts_kvkk`	Boolean, indicates if the customer has accepted KVKK (data protection)
`customer_allows_sms`	Boolean, indicates if the customer has opted in for SMS messages
`customer_allows_call`	Boolean, indicates if the customer has opted in for phone calls
`customer_allows_email`	Boolean, indicates if the customer has opted in for email

400 Bad Request: If the phone number is invalid or the customer is not found
401 Unauthorized: If the request is not authenticated with the proper bearer token

POST

/ext/customers/kvkk-check

Authentication

Example request body

{
  "customer_phone": "+905395555555"
}

Example response

{
  "customer_name": "Yusuf",
  "customer_surname": "Karaaslan",
  "customer_phone": "+905395555555",
  "customer_accepts_kvkk": true,
  "customer_allows_sms": true,
  "customer_allows_call": true,
  "customer_allows_email": false
}

Error responses

Get Stores

Returns the stores belonging to the location.

GET

/ext/data/stores

Example response

[
    {
        "_id": "NJ8GHxQZae",
        "store_name": "3M Migros"
    },
    {
        "_id": "4ymyCScTl",
        "store_name": "Allcar Yıkama"
    },
    {
        "_id": "S1Z_g1zFs",
        "store_name": "Anka Çiçekçilik"
    },
    {
        "_id": "Vkxp4eQWTg",
        "store_name": "Atasun Optik"
    },
    {
        "_id": "NkxRNgX-ag",
        "store_name": "Bay Döner"
    },
    {
        "_id": "NkXRExmZax",
        "store_name": "Burger King"
    }
]