Introduction
CDP API
Campaign
Customers
Locations

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

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

Property Description
customer_phone (required) String must start with "+" and can only contain numbers and plus signs.
customer_email (required for new customers) String
customer_name (required for new customers) String, customer's first name
customer_surname (required for new customers) String, customer's last name
customer_gender (required for new customers) String, either male, female, unknown
customer_birthdate (required for new customers) String, in DD/MM/YYYY format.
customer_country (optional) String, (Ülke Kodu) Must have 2 characters. (TR,DE,GE)
customer_province (optional) String, (İl)
customer_district (optional) String, (İlçe)
customer_address (optional) String, (Adres)
customer_locality (optional) String, (Mahalle)
customer_accepts_kvkk (required for new customers) Boolean, Customer's acceptance of KVKK (data protection).
customer_accepts_kvkk_at (required for new customers) Number, Timestamp of customer's KVKK acceptance.
customer_allows_sms (optional) Boolean, Customer's opt-in status for SMS messages.
customer_allows_sms_at (required for sms consent) Number, Timestamp of customer's opt-in status for SMS.
customer_allows_call (optional) Boolean, Customer's opt-in status for phone calls.
customer_allows_call_at (required for call consent) Number, Timestamp of customer's opt-in status for phone.
customer_allows_email (optional) Boolean, Customer's opt-in status for email.
customer_allows_email_at (required for email consent) Number, Timestamp of customer's opt-in status for email.

NOTE: If 'customer_allows_sms', 'customer_allows_call', 'customer_allows_email', 'customer_accepts_terms_conditions', 'customer_accepts_kvkk' fields are not sent for a new user, it is set to false. NOTE: customer_accepts_kvkk must always be true to register a new customer.

POST
/ext/customers/upsert

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": "Istanbul",
  "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": 1682171994253,
  "customer_allows_sms": true,
  "customer_allows_sms_at": 1682171994253,
  "customer_allows_call": true,
  "customer_allows_call_at": 1682171994253,
  "customer_allows_email": false,
  "customer_allows_email_at": 1682171994253
}

Example response

{
  "_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": "Istanbul",
  "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_allows_sms": true,
  "customer_allows_call": true,
  "customer_allows_email": false
}

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"
    }
]
CDP API Documentation