Retrieve Attribute Values

Retrieve Customer Attribute Values

This API returns all the Customer Attribute values of the given Customer Profile, for a specific System of Record. It concerns both custom and SDK SORs. Please note that this API is not adapted to massive retrieving that should rather use exports API.

Query parameter

Response

Without requesting dates ( with_validity_dates=false ):

{
  "success": true,
  "result":
    {
      "customer_id": "maximillian",
      "customer_id_type": "user_id",
      "attribute_values": {
        "first_name": "maximillian",
        "last_name": "weber",
        "contract_type": "Premium",
        "client_type": null,
        "hobbies": [],
        "favorite_team": "France",
        "languages": ["French", "English"],
        "city": null,
        "region": null,
      }
    }
}

With the validity dates ( with_validity_dates=true ):

{
  "success": true,
  "result":
    {
      "customer_id": "maximillian",
      "customer_id_type": "user_id",
      "attribute_values": {
        "first_name": {
          "value": "maximillian",
          "since": "2017-10-25T23:48:46:299Z"
        },
        "last_name": {
          "value": "weber",
          "since": "2017-10-25T23:48:46:299Z"
        },
        "contract_type": {
          "value": "Premium",
          "since": "2017-11-13T06:55:21:437Z"
        },
        "client_type": {
          "value": null,
          "since": null
        },
        "hobbies": {
          "value": [],
          "since": null,
        },
        "languages": {
          "value": ["French", "English"],
          "since": "2017-12-05T11:34:51:701Z",
        },
        "city": {
          "value": null,
          "since": null
        },
        "region": {
          "value": null,
          "since": null
        },
      }
    }
}

Export Customer Profiles

This API exports a batch of customer profiles along with the associated attributes values.

!!! Using updated_since query parameter is recommended to speed up the processing time. By using this parameter, the API returns only the list of attribute values that changed since the specified date. The other filters and pagination are also used to limit the amount of profiles for each request.

Query parameters

Example

system_of_record_identifier;customer_attribute_identifier;customer_attribute_key;customer_attribute_value;customer_id_type;customer_id
SOR-SDK_2a116e0767a7dc76e85a5ef85434d92b;FACA_lEDOA5CbP5YzFKcM;team;team1;device_id;3f976ddac73f7d80
SOR-SDK_2a116e0767a7dc76e85a5ef85434d92b;FACA_lEDOA5CbP5YzFKcM;team;team2;user_id;user1

Feed Customer Attributes

Feed Customer Attributes with values

Feeding a Customer Profile with values can be done either from the SDK or from other external systems. This chapter does not cover the SDK functionality, but focuses on external systems.

Body parameters

It takes a JSON object containing the following keys:

Possible attribute values:

Here is the description of the possible action types:

Example

{
    "sor": "SOR_XXXX",
    "api_key": "XXXXXXXX",
    "customer_attribute_values": [
        {
            "customer_id" : "098713490",
            "attribute_key" : "contract_type",
            "attribute_value" : "Premium"
        },
        {
            "customer_id" : "098713490",
            "attribute_key" : "hobbies",
            "attribute_value" : "Sport",
            "action_type" : "ADD"
        },
        {
            "customer_id" : "098713490",
            "attribute_key" : "hobbies",
            "attribute_value" : "Reading",
            "action_type" : "REMOVE"
        },
        {
            "customer_id" : "098713490",
            "attribute_key" : "hobbies",
            "attribute_value" : "Reading;Hiking;Singing",
            "action_type" : "UPSERT"
        },
        {
            "customer_id" : "098713491",
            "attribute_key" : "fav_team",
            "attribute_value" : "France"
        },
        {
            "customer_id" : "098713492",
            "attribute_key" : "fav_team",
            "attribute_value" : "Italy"
        }
    ]
}

In the example above contract_type and fav_team are attributes of type String.hobbies is an attribute of type SET.

The request body above will imply the following:

• Add Premiumvalue to contract_type for the customer 098713490,
• Add Sportvalue to the set of values of hobbies for the customer 098713490,
• Remove Readingfrom the set of values of hobbies for the customer 098713490 if this value is part of the set, otherwise, it does nothing,
• Replace all set values by Reading;Hiking;Singing for the customer 098713490,
• Add France to fav_teamfor customer 098713491,
• Add Italy to fav_teamfor customer 098713492.

Response

The response will return the request_id that will allow to track the progress of the request.

{
    "success" : true,
    "result": {
        "requestId": "1522771731812-vl9cUtxfZtMl"
    },
    "errorMessage": null,
    "errorCode": 0
}

Import attribute values from CSV

For large attribute data sets and recurrent imports, it's recommended to send CSV files with attribute values to Followanalytics through the following API. All CSV files must use UTF-8 encoding and it's preferable to compress them as gzip files.

Query parameter

You can also upload the file directly as if part of a web form. The key for the file must be file.

Response

Processing is done asynchronously, including the download of your file. When you call the API, a job ID is returned if all parameters are valid.

Use this job ID in communicating with us if you have an issue with your jobs.

{
    "success": true,
    "result": {
        "jid": "c98de272c6e42d93e7d2b969",
        "import_id": "import_id_1"
    }
}

CSV file content

It's recommended to use gzip compressed files to increase the performance. The CSV file itself must be encoded with UTF-8 and have the following header:

user_id,attribute_key,value,action_type

Set values

Each line for a Set attribute is considered as the new full state of the Set. In other words, for a given user and given Set attribute, any list of values provided replaces all current values.

Values for a given user and set are put on the same line, separated by semi-colons. For instance, a CSV line where we set value1 and value2 as the two new and only values of the Set identified by the key my_set is as follows:

abcd,my_set,value1;value2,UPSERT

Example

The following CSV file:

user_id,attribute_key,value,action_type
abcd,my_set,value1;value2,UPSERT
abcd,my_set,value3;value4
efgh,my_set,value2,REMOVE
xyzw,my_set,,DEL
xyzw,my_set,value1,ADD
efgh,my_number,1234,

• sets values value1 and value2 for Set of key my_set, for user abcd
• sets values value3 and value4 for Set of key my_set, for user abcd
• removes value value2 from the Set of key my_set, for user efgh
• removes all values of the Set of key my_set, for user xyzw
• adds value1 to the Set of key my_set, for user xyzw
• sets value 1234 for Number attribute of key my_number, for user efgh

Hosted at https://path.to/my/file.csv, you would send it as follows:

{
    "file_url": "https://path.to/my/file.csv",
    "sor_id": "SOR_767yUpsMJoTWi0mz",
    "api_key": "XXXXXXXX"
}

CSV attributes import generation

Generate a CSV template that can be used for the batch CSV import API.

Query parameter

Monitoring of CSV imports

You can verify the status of your recent imports. The import job ids and the details of import errors are available for one week.

Query parameter

There are no parameters for this query.

Response

The query returns the list of import jobs for the currently logged in user.

{
    "success": true,
    "result": {
        "import_id_1": "2019-01-02 11:12:13",
        "import_id_2": "2019-02-03 11:12:13",
        "import_id_3": "2019-03-03 11:12:13"
    }
}

Query parameter

Response

The query returns the list of import jobs for the currently logged in user or, in alternative, for a specific customer.

{
    "success": true,
    "result": {
        "attribute_errors": [
            {
                "import_id": "import_id_1",
                "error_type": "empty_key",
                "customer_id": "Bob",
                "key": "age",
                "date": "2019-01-02T11:12:13",
                "message": "attributeKey is empty",
                "raw": "{\n\"sor\":\"SOR_XXXX\",\n\"api_key\":\"XXXXXXXX\",\n\"customer_attribute_values\": [\n{\n\"customer_id\" :\"098713490\",\n\"attribute_key\" :\"contract_type\",\n\"attribute_value\" :\"Premium\"\n}\n]\n}",
                "sor": "SOR_XXX",
                "source": "AttributeCleaner",
            }
        ]
    }
}

• key: attribute key
• source: technical field identifying the part of the processing pipeline where the error has occured
• message: the description of the error
• raw: raw json of the original attribute value request
• error_type: the type of the error.

error_type can be a technical error :

• KAFKA_DELIVERY_FAILED: failed to send attribute values to Kafka
• FILE_TRANSFER_ERROR: failed to retrieve import file

Or a content error :

• EMPTY_SOR: the System of Records identifier is not specified
• INVALID_CUSTOMER_ID: the customer id is invalid
• EMPTY_KEY: the attribute key is not specified
• TOO_LONG_KEY: the attribute key has more than 256 characters
• EMPTY_VALUE: the attribute value is not specified
• INVALID_VALUE: the attribute value is invalid
• TOO_LONG_VALUE: the attribute value or a value in the SET has more than 256 characters
• TOO_LONG_SET_SIZE: the attribute of type SET has more than 1000 elements
• UNDEFINED_ATTRIBUTE: the attribute is not defined in System of Records
• DISABLED_ATTRIBUTE: the attribute is disabled
• UNKNOWN_TYPE: the type of the attribute is unknown
• INVALID_ACTION: the action specified is invalid
• PARSING_FAILED: failed to parse the import file
• FILE_ENCODING: the content of the import file is not properly UTF-8 configured. Can also indicate that the file transfer did not work correctly

Systems of Records

List of SORs

This call lists all the Systems Of Records available for your entity.

There are two types of systems of records (key type):

• app: SDK-based SoR, related to an app
• custom: a custom SoR, defined by a user of your entity

If the param type is invalid, no system of records are returned.

Query parameter

Response

{
    "success": true,
    "result": [    
        {
            "name": "SOR for app XYZ",
            "identifier": "SOR-SDK_your.package.name",
            "type": "app",
            "api_keys": [
                "FH7nIacl4f"
            ],
            "attributes_count": 0,
            "disabled": false,
            "customer_attributes": []
        },                   
        {
            "name": "Custom SOR",
            "identifier": "SOR_rldYf1ypGTfvKjl-",
            "type": "custom",
            "api_keys": [
                "2ypbGlj7g0SHOe"
            ],
            "attributes_count": 2,
            "disabled": true,
            "customer_attributes": [
                {
                    "identifier": "FACA__eTzcrLpnuJq",
                    "key": "key1",
                    "label": "label_name1",
                    "value_type": "String",
                    "disabled": false
                },
                {
                    "identifier": "FACA_t7NiJiYd_kGj",
                    "key": "key2",
                    "label": "label_name1",
                    "value_type": "Number",
                    "disabled": false
                }
              ]
          }
       ]
   }

View SOR

Gets information about a single System of Records. This is more detailed than the list because it contains information about the attributes as well.

Query parameter

Response

{
    "success": true,
    "result":{
        "name": "Custom SOR",
        "identifier": "SOR_rldYf1ypGTfvKjl-",
        "type": "custom",
        "api_keys": [
            "2ypbGlj7g0SHOe"
        ],
        "attributes_count": 2,
        "disabled": true,
        "customer_attributes": [
            {
                "identifier": "FACA__eTzcrLpnuJq",
                "key": "key1",
                "label": "label_name1",
                "value_type": "String",
                "disabled": false
            },
            {
                "identifier": "FACA_t7NiJiYd_kGj",
                "key": "key2",
                "label": "label_name1",
                "value_type": "Number",
                "disabled": false
            }
          ]
        }
    }

Create, Update, Delete SOR

Create

Creates a custom SoR, with a name.

Please note that SDK-based Systems of Records are created automatically, so there is no need to create on manually.

Body parameter

Example

{
    "name": "My Custom SoR"
}

Response

{
    "success": true,
    "result": {
        "name": "My Custom SoR",
        "identifier": "SOR_767yUpsMJoTWi0mz",
        "type": "custom",
        "api_keys": [
            "tBqL8qvvAhfyAQ"
        ],
        "attributes_count": 0,
        "disabled": false
    }
}

Update

Modifies a System of Records.

Only custom system of records can be modified.

Query parameter

Body parameter

Example

{
    "name": "My Custom SoR"
}

Response

{
    "success": true,
    "result": {
        "name": "My Custom SoR",
        "identifier": "SOR_767yUpsMJoTWi0mz",
        "type": "custom",
        "api_keys": [
            "tBqL8qvvAhfyAQ"
        ],
        "attributes_count": 0,
        "disabled": false
    }
}

Delete

Deletes a System of Records.

Please note that this is not very useful for live SDK-based Systems of Records, as the entry will automatically be regenereted upon next call. In that case, disabling the System of Records is advised.

Also, please note that only custom system of records can be deleted.

Query parameter

Response

{
    "success": true
}

Disable & Enable SOR

Disable

Disables a System of Records. Trying to disable an already disabled system of record will result in an API error.

Query parameter

Response

{
    "success": true
}

Enable

Enables a System of Records. Trying to enable an already enabled system of record will result in an API error.

Query parameter

Response

{
    "success": true
}

Customer Attributes

This section covers the definition of the attributes onto SORs: key, type, and so on.

View Customer Attribute

Gets information about a single customer attribute.

Query parameter

Response

{
    "success": true,
    "result": {
        "identifier": "FACA_eVYy7KP9PZqP_B8w",
        "key": "is_valid",
        "label": "Is valid",
        "value_type": "Boolean",
        "disabled": false,
        "system_of_record_identifier": "SOR-SDK_2a116e0767a7dc76e85a5ef85434d92b"
    }
}

Create, Update, Delete Customer Attribute

Create

Creates a customer attribute, with a custom label and a type.

Body parameter

Example

{
    "system_of_record_identifier": "SOR-SDK_c7a5a35762fd9e50006fd77215599dfb",
    "key": "My Attr",
    "label": "my_attr",
    "type": "String"
}

Response

{
    "success": true,
    "result": {
        "identifier": "FACA_0OkzOc8",
        "key": "My Attr",
        "label": "my_attr",
        "value_type": "String",
        "disabled": false
    }
}

Modify

Modifies a customer attribute. Only the label of a customer attribute can be changed.

Query parameter

Body parameter

Example

{
    "label": "Test"
}

Response

{
    "success": true,
    "result": {
        "identifier": "FACA_eVYy7KP9PZqP_B8w",
        "key": "is_valid",
        "label": "Test",
        "value_type": "Boolean",
        "disabled": false
    }
}

Delete

Deletes a customer attribute along with all the values associated to it.

It is not advised to delete attributes from a live System of Records. Because of auto-declaration, the attribute is going to be recreated upon the next receival of a value. If you don't want to receive these values, but you cannot modify the external system, you can disable the attribute instead.

An attribute that is currently being used in the filters of a campaign or segment cannot be deleted.

Query parameter

Response

{
    "success": true
}

Disable & Enable Customer Attribute

Disable

By default, all attributes are enabled, but it is possible to disable one. By doing so, all future values sent for this attribute will be refused, until the attribute is enabled again.

Query parameter

Response

{
    "success": true
}

Enable

Enables a previously disabled attribute. Enabling an already enabled attribute is a no-op.

Query parameter

Response

{
    "success": true
}

Attributes removed since a praticular date

Returns all the attributes removed for the given system of record.

Query parameter

Response

{
    "success":true,
    "result":[
        {
            "id":32500,
            "system_of_record_id":1,
            "key":"attr1",
            "value_type":"Number",
            "label":"attributeTest1",
            "created_at":"2019-09-03T16:01:55.852Z",
            "updated_at":"2020-01-06T11:00:26.082Z",
            "identifier":"FACA_FgzfBvu",
            "removed":true,
            "disabled":false
        },
        {
            "id":33050,
            "system_of_record_id":1,
            "key":"attr2",
            "value_type":"String",
            "label":"attributeTest2",
            "created_at":"2019-09-25T14:52:04.261Z",
            "updated_at":"2019-12-26T16:54:33.275Z",
            "identifier":"FACA_2BmN8T0",
            "removed":true,
            "disabled":false
        }
    ]
}