Skip to content

Customer Data

Jump to bottom
aditya-utama-wijaya edited this page Dec 24, 2018 · 45 revisions

Customer data is your customer records which may come from your CRM system. Before making API request to create or update customer data, you need to understand customer data format:

For Customer Data, you could:

octocat Both Create and Update API will allow 32mb request body, so please make separate requests if all customer data size is over 32mb.

Customer Data Format

CRM data could include several types of data:

1 . Customer identification data:

  • customuid

    • A mandatory column

    • Refers to the customer ID in your CRM system.

    • Can be sequential numbers or any random IDs, but it must be unique for each customer

    • One customuid must refer to only one customer

  • emailsha256

    • An optional column
    • Please change the customers' email addresses into lower-case letters, and then transform them into SHA-256 hashed format

  • idfa

    • An optional column
    • Represents the users' mobile device IDs

  • dmpid

    • An optional column
    • If you are using any Data Management Platform (DMP) service, you could put your customers' DMP ID here, to add insights back to your DMP service.

2 . Customer feature data: data to describe a customer, such as age, region, city, interest, income amount, etc.

  • Supported data types:

    • string/text (Please use prefix txt_for the feature names)
    • numerical (Please use prefix num_for the feature names)
    • array/multi-values (Please use prefix attr_for the feature names)

  • These are some examples of how to name a feature in the CRM data:

    • Attribute features:

      Describe personal data about customer, such as txt_city = 'Taipei', num_income = 100, num_customer_value = 200, etc.

    • Categorical features:

      Describe which category each customer belongs to, such as txt_customer_group = 'A', num_customer_income_group = 1, etc.

    • Preference features:

      Describe customers' preferences, such as txt_preference_city = 'Taipei', attr_preference_regions = 'north, south, east', etc.

    • Monetary features:

      Describe customers' monetary data. Could be in average, sum, or boolean format. E.g., num_purchase_amount_monthly = 100, num_purchase_amount_last_year = 1000, num_purchase_over_1000_last_quarter = 1, etc.

    • Boolean / flag features

      Describe the customers' status using 1 or 0, where 1 represents true, and 0 represents false. E.g., num_flag_vip, num_flag_new_customer, num_flag_email_subscriber, etc.

    • Frequency features

      Describe the customer features based on frequency of an event. Could be in boolean, count, or average format. E.g., num_visit_last_week = 10, num_average_monthly_visit = 7, etc.

    • Recency features

      Describe the customer features based on recency events. Could be in boolean or numerical data type, such as num_flag_visit_last_week = 1, num_visit_last_time_in_days = 10, etc.

3 . Customer goal data: data to describe customers' status or value for a specific goal

There are 2 types of customer goal data: binary goal, e.g., has or has not purchased, purchased more or less than 500 in last month, etc., and timestamp goal, e.g., when was the last purchase, when did the user become a VIP member, etc.

  • Binary goal

    • Supported data types All goal values are either 1, 0, or leave value empty (to indicate missing values).

    • You can only name your CRM data with these prefixes:

      • goal_no_visit_xxx whether the user visited a property or not
      • goal_churn_xxx whether the user has churned, has a chance of churning, or has not churned
      • goal_loyal_xxx whether the user is a loyal customer
      • goal_action_xxx whether the user has accomplished an action
      • goal_click_xxx whether the user has clicked on desired property
      • goal_pageview_xxx whether the user has page views on desired property or how many
      • goal_conversion_xxx whether the customer has conversion events (any type of conversion events)
      • goal_purchase_xxx whether the customer has purchase events

    • These are some examples of how to name a feature in the CRM data:

      • Direct goals, e.g.:

        • goal_purchase_premium_program = 1 to label that particular customer has purchased the premium program

      • Product specific goals (mostly used in cross-selling recommendation scenarios), e.g.:

        • goal_purchase_product_abc = '' (empty value) to label that particular customer has NOT purchased product abc yet

      • Frequency goals, e.g.:

        • goal_conversion_visit_10_times_last_year = 0 to label that particular customer visited the site less than 10 times last year

      • Monetary goals, e.g.:

        • goal_purchase_average_amount_1000_last_quarter = 1 to label that particular customer's purchases worth more than 1000 dollars on average last quarter

  • Timestamp goal

    • Supported data types
      All goal values are either Unix time (integer, not float), 0, or leave value empty (to indicate missing values).

      • goal_conversion_xxx_timestamp => when the customer converted (any type of conversion events)
      • goal_purchase_xxx_timestamp => the last time a particular customer made purchase of something

    • These are some examples of how to name a feature in the CRM data:

      • Direct goals, e.g.:
        • goal_conversion_vip_timestamp = 1512011429 to label when the customer became a VIP member
      • Product specific goals (mostly used in cross-selling recommendation scenarios), e.g.:
        • goal_conversion_health_column_timestamp = 1512011538 to label when (last time) a customer read the an article from health column
      • Recency goals, e.g.:
        • goal_purchase_last_month_timestamp = 1512012954 to label when the customer made last purchase in last month

Customer Data Example

JSON format

{
	"header": ["customuid", "emailsha256", "idfa", "txt_gender", "txt_region", "num_spending", "attr_interest", "goal_conversion_subscription", "goal_conversion_subscription_timestamp"],
	"data": [
		["crm001", "f660ab912ec121d1b1e928a0bb4bc61b15f5ad44d5efdc4e1c92a25e99b8e44a", "D14C3XX6-6FXF-413F-B7D6-70B458A7EIYY", "M", "north", 2135, "cooking, writing", 1, 1514254499],
		["crm002", "7599502b735425943fffc167b4c9cfb072d028c109ee07501c8711a4fe0e12e7, a862f0e6ac9ce4c636cc9a49b621215ae0e9bace8f7964e8486205c9f0f2079e", "72XX41DB-FEX1-3446-A019-FEB8F2AFE839", "F", "south", 1234, "reading, biking", ,],
		["crm003", "x980ab912ec121d1b1e928a0bb4bc61b15f5ad44d5efdc4e1c92a25e99b8e44a", "490953XE-6FE4-41A1-EA38-A186A06228E9", "F", "central", 8274, "reading, writing", 1, 1534254485],
		["crm004", "y252f0e6ac9ce4c636cc9a49b621215ae0e9bace8f7964e8486205c9f0f2079e", "YYX4CXXX-DXXF-FX3F-AXD6-90BX58A7GEXA", "M", "north", 9713, "biking, writing", 1, 1521254435],
		["crm005", "y970ab912ec121d1b1e928a0bb4bc61b15f5ad44d5efdc4e1c92a25e99b8e44a", "0X5AX1FA-EY2E-4XB6-8262-67Y6F8Y4DD74", "M", "south", 7291, "cooking,writing", ,],
		["crm006", "z152f0e6ac9ce4c636cc9a49b621215ae0e9bace8f7964e8486205c9f0f2079e", "X48153XE-6FE4-41A1-EA38-A186A06228E9", "F", "central", 2481, "reading, biking", 1, 1519254468]
	]
}

CSV format

customuid, emailsha256, idfa, txt_gender, txt_region, num_spending, attr_interest, goal_conversion_subscription, goal_conversion_subscription_timestamp
crm001,f660ab912ec121d1b1e928a0bb4bc61b15f5ad44d5efdc4e1c92a25e99b8e44a,D14C3XX6-6FXF-413F-B7D6-70B458A7EIYY,M,north,2135,"cooking,writing",1,1514254499
crm002,"7599502b735425943fffc167b4c9cfb072d028c109ee07501c8711a4fe0e12e7,a862f0e6ac9ce4c636cc9a49b621215ae0e9bace8f7964e8486205c9f0f2079e",72XX41DB-FEX1-3446-A019-FEB8F2AFE839,F,south,1234,"reading,biking",,
crm003,x980ab912ec121d1b1e928a0bb4bc61b15f5ad44d5efdc4e1c92a25e99b8e44a,490953XE-6FE4-41A1-EA38-A186A06228E9,F,central,8274,"reading,writing",1,1534254485
crm004,y252f0e6ac9ce4c636cc9a49b621215ae0e9bace8f7964e8486205c9f0f2079e,YYX4CXXX-DXXF-FX3F-AXD6-90BX58A7GEXA,M,north,9713,"biking,writing",1,1521254435
crm005,y970ab912ec121d1b1e928a0bb4bc61b15f5ad44d5efdc4e1c92a25e99b8e44a,0X5AX1FA-EY2E-4XB6-8262-67Y6F8Y4DD74,M,south,7291,"cooking,writing",,
crm006,z152f0e6ac9ce4c636cc9a49b621215ae0e9bace8f7964e8486205c9f0f2079e,X48153XE-6FE4-41A1-EA38-A186A06228E9,F,central,2481,"reading,biking",1,1519254468
  • octocat idfa, email, and emailsha256 are allowed to use multiple values, please use , to separate them and use " to quote them, ex: "email1, email2"
  • If you have any missing values, please keep it empty. Please refer to the emailsha256 field in the example

Query All Customer Data Resources

You can use the API to get all available data cells and api to update customer data files into Appier Aixon Platform. The data cells id the resourceId of the data cell.

API Information

Name Value
HTTP Method GET
URL https://${AIXON-API-HOST}/api_upload/v1/csv-upload

Example:

Request

curl -k -v "https://${AIXON-API-HOST}/api_upload/v1/csv-upload" \
     -H "x-api-key: ${api-key}" \
     -H "Content-Type: application/json; charset=utf-8"

Response

{
  "message": [
    {
      "DESCRIPTION": "GET all csv-upload resources", 
      "SUPPORT_METHODS": [
        "GET"
      ], 
      "URL": "/api_upload/v1/csv-upload"
    }, 
    {
      "DESCRIPTION": "Create a new CSV Upload node", 
      "SUPPORT_METHODS": [
        "PUT"
      ], 
      "URL": "/api_upload/v1/csv-upload"
    }, 
    {
      "DESCRIPTION": "Upload csv data data_id_1: test_data_one", 
      "SUPPORT_METHODS": [
        "PUT", 
        "PATCH"
      ], 
      "URL": "/api_upload/v1/csv-upload/data_id_1"
    }, 
    {
      "DESCRIPTION": "Upload csv data data_id_2: test_data_two", 
      "SUPPORT_METHODS": [
        "PUT", 
        "PATCH"
      ], 
      "URL": "/api_upload/v1/csv-upload/data_id_2"
    }
  ], 
  "status": "success"
}

Create Customer Data Resource

This API will create a customer data cell in AIXON.

octocat Each api request allows 32mb request body, so please make separate requests if all customer data size is over 32mb.

API Information

Name Value
HTTP Method PUT
HTTP Header x-node-description
URL https://${AIXON-API-HOST}/api_upload/v1/csv-upload

Example:

Request

curl -k -v "https://${AIXON-API-HOST}/api_upload/v1/csv-upload" \
     -X PUT \
     -H "x-api-key: ${api-key}" \
     -H "Content-Type: application/json; charset=utf-8" \
     -H 'x-node-description: This new node name' \
     -d '{
  "header": ["customuid", "emailsha256", "idfa", "txt_region", "num_spending", "attr_interest", "goal_conversion_subscription", "goal_conversion_subscription_timestamp"],
  "data": [
  	["crm001", "f660ab912ec121d1b1e928a0bb4bc61b15f5ad44d5efdc4e1c92a25e99b8e44a", "D14C3XX6-6FXF-413F-B7D6-70B458A7EIYY", "north", 2135, "cooking, writing", 1, 1514254499],
  	["crm002", "7599502b735425943fffc167b4c9cfb072d028c109ee07501c8711a4fe0e12e7, a862f0e6ac9ce4c636cc9a49b621215ae0e9bace8f7964e8486205c9f0f2079e", "72XX41DB-FEX1-3446-A019-FEB8F2AFE839", "south", 1234, "reading, biking", ,],
  	["crm003", "x980ab912ec121d1b1e928a0bb4bc61b15f5ad44d5efdc4e1c92a25e99b8e44a", "490953XE-6FE4-41A1-EA38-A186A06228E9", "central", 8274, "reading, writing", 1, 1534254485],
  	["crm004", "y252f0e6ac9ce4c636cc9a49b621215ae0e9bace8f7964e8486205c9f0f2079e", "YYX4CXXX-DXXF-FX3F-AXD6-90BX58A7GEXA", "north", 9713, "biking, writing", 1, 1521254435],
  	["crm005", "y970ab912ec121d1b1e928a0bb4bc61b15f5ad44d5efdc4e1c92a25e99b8e44a", "0X5AX1FA-EY2E-4XB6-8262-67Y6F8Y4DD74", "south", 7291, "cooking,writing", ,]
        ]
      }'

Response

{
 "message": {
   "RESOURCE_ID": "example000data000cell000resource000id",
   "STATUS": "CREATED"
 },
 "status": "success"
}

Description

Create a new data node and upload its data at the same time. Please put the node description in HTTP Header: x-node-description

Update Customer Data Resource

This API will be used for update existing customer record and append new customer record for the existing customer data cell in AIXON. This API will be used for incremental update purpose.

Once the API received the update request, AIXON will queue the update in scheduler. It may take some time for AIXON completes the update.

octocat Each api request allows 32mb request body, so please make separate requests if all customer data size is over 32mb.

octocat You could make multiple update customer data requests until all the customer data has been updated or appended.

API Information

Name Value
HTTP Method PATCH
URL https://${AIXON-API-HOST}/api_upload/v1/csv-upload/${resourceId}

Example:

Request

curl -k -v "https://${AIXON-API-HOST}/api_upload/v1/csv-upload/${resourceId}" \
     -H "x-api-key: ${api-key}" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d '{
  "header": ["customuid", "emailsha256", "idfa", "txt_region", "num_spending", "attr_interest", "goal_conversion_subscription", "goal_conversion_subscription_timestamp"],
  "data": [
  	["crm001", "2b96e23f4121c0d939da02ac6c842ee508496d0de2bfbc37ad6c3fe1c161d618", "D14C3XX6-6FXF-413F-B7D6-70B458A7EIYY", "north", 5321, "cooking, writing", 1, 1515254499],
  	["crm002", "c4d745d3e1d5ac1f18fa3d53b995d855fdbab061ecf9572dd7304393ba91f69c", "72XX41DB-FEX1-3446-A019-FEB8F2AFE839", "south", 4321, "reading, biking", 1, 1534254485],
  	["crm006", "6aaebdb23a633cf5c6f60d010628ad79f7777673d64bbe210fba83149d936919", "690953XE-6FE4-41A1-EA38-A186A06228E9", "north", 2135, "cooking, writing", 1, 1514254499],
  	["crm007", "772262ec751ad9da00ae41f4adf959e4a765511f9fd751e72cb37581888be3a4", "7YX4CXXX-DXXF-FX3F-AXD6-90BX58A7GEXA", "south", 1234, "reading, biking", ,],
  	["crm008", "82677c9ab3e3e907214afe7bdd880c2a5f5e19873613f6ad285a39921905ac26", "8X5AX1FA-EY2E-4XB6-8262-67Y6F8Y4DD74", "north", 9713, "biking, writing", 1, 1521254435]
        ]
      }'

Response

{
 "message": {
   "RESOURCE_ID": "example000data000cell000resource000id",
   "STATUS": "RECEIVED"
 },
 "status": "success"
}

Description

You can use PATCH /csv-upload/${resourceId} to manage incremental data update. The ${resourceId} here is the resource_ID you got before when creating a new customer data cell.

  • octocat The ${resourceId} is data cell id. The ${resourceId} could be retrieved from create customer data API response or customer data cell URL in AIXON. In this example, the RESOURCE_ID is example000data000cell000resource000id.
  • octocat For existing customuid data, this API will update the original customer record. For new customuid data, this API will append new customer record into the data cell. In this example, the existing crm001 and crm002 will be updated. The crm006, crm007 and crm008 will be appended into customer data cell.
  • octocat The column counts, names and orders must be exactly the same with what you uploaded before. If they are different, please use Create a New API Upload Data instead.

Overwrite Customer Data Resource

This API will be used for overwrite existing customer record and could add new columns for the original data cells. However, you could only add new columns and do NOT allow to rename or remove original columns. This API will be used for incremental update purpose.

Once the API received the update request, AIXON will queue the update in scheduler. It may take some time for AIXON completes the update.

octocat Each api request allows 32mb request body, so please make separate requests if all customer data size is over 32mb.

octocat You could make multiple overwrite customer data requests until all the customer data has been overwritten.

API Information

Name Value
HTTP Method PUT
URL https://${AIXON-API-HOST}/api_upload/v1/csv-upload/${resourceId}

Example:

Request

curl -k -v "https://${AIXON-API-HOST}/api_upload/v1/csv-upload/${resourceId}" \
     -H "x-api-key: ${api-key}" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d '{
  "header": ["customuid", "emailsha256", "idfa", "num_a", "num_b", "num_c", "num_d", "num_e", "num_f", "txt_g", "goal_conversion_abc", "goal_purchase_xyz"],
  "data": [
  ["crm001", "2b96e23f4121c0d939da02ac6c842ee508496d0de2bfbc37ad6c3fe1c161d618", "D14C3XX6-6FXF-413F-B7D6-70B458A7EIYY", "M", "north", 5321, "cooking, writing", 1, 1515254499],
  ["crm002", "c4d745d3e1d5ac1f18fa3d53b995d855fdbab061ecf9572dd7304393ba91f69c", "72XX41DB-FEX1-3446-A019-FEB8F2AFE839", "F", "south", 4321, "reading, biking", 1, 1534254485],
  ["crm006", "6aaebdb23a633cf5c6f60d010628ad79f7777673d64bbe210fba83149d936919", "690953XE-6FE4-41A1-EA38-A186A06228E9", "M", "north", 2135, "cooking, writing", 1, 1514254499],
  ["crm007", "772262ec751ad9da00ae41f4adf959e4a765511f9fd751e72cb37581888be3a4", "7YX4CXXX-DXXF-FX3F-AXD6-90BX58A7GEXA", "F", "south", 1234, "reading, biking", ,],
  ["crm008", "82677c9ab3e3e907214afe7bdd880c2a5f5e19873613f6ad285a39921905ac26", "8X5AX1FA-EY2E-4XB6-8262-67Y6F8Y4DD74", "M", "north", 9713, "biking, writing", 1, 1521254435]
        ]
      }'

Response

{
 "message": {
   "RESOURCE_ID": "example000data000cell000resource000id",
   "STATUS": "RECEIVED"
 },
 "status": "success"
}

Description

You can use PUT /csv-upload/${resourceId} to overwrite the original data cell and add columns. The ${resourceId} here is the resource_ID you got before when creating a new customer data cell.

  • octocat The ${resourceId} is data cell id. The ${resourceId} could be retrieved from create customer data API response or customer data cell URL in AIXON. In this example, the RESOURCE_ID is example000data000cell000resource000id.
  • You could only add new column. All the original columns MUST be kept.
  • You cannot remove the original column. If you do NOT have the values for the original column, just leave the value empty.
  • You cannot rename the original column.

Home | Copyright © 2017 Appier.com

AIXON API Document

Overview

Basics

Site Category

Product Category

Customer Data

Customer Insight

Clone this wiki locally