Endpoint and Authentication

Please refer to the API overview section to get the API endpoint, query format and authentication process

Customer Profiles

List

GET /api/customer_profiles?sor_identifiers=sor_identifiers&customer_id_type=customer_id_type&attribute_keys=attribute_keys&page=page&num_per_page=num

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

Pagination and filters are used to limit the amount of profiles for each request.

Query parameters

Property Type Description Default
customer_id_type string Filter by the type of customer id, options: user_id, device_id -
customer_ids string List of customer IDs, separated by commas, used to filter the customer profiles returned in the API output -
sor_identifiers string List of SOR identifiers separated by commas, used to define the Systems of Records to return for each profile in the output -
attribute_keys string List of attribute keys separated by commas, used to filter the SOR keys to return for each profile in the API output: only SORs containing a key matching this parameter will be returned, and only this key will be listed -
page integer The page number to fetch 1
num_per_page integer The maximal number of profiles per page. 2000

Response

Status: 200 OK

{
  "success": true,
  "result": {
    "total_pages": 2,
    "total_profiles": 20,
    "profiles": [
      {
        "customer_id": "maximillian_weber@ritchiehyatt.name",
        "customer_id_type": "user_id",
        "attributes": {
          "global": {
            "first_name": "maximillian",
            "last_name": "weber",
            "email": null,
            "date_of_birth": null,
            "gender": null,
            "country": null,
            "city": null,
            "region": null,
            "profile_picture_url": null
          },
          "SOR-SDK_2a116e0767a7dc76e85d566": {
            "favorite_team": "PSG",
            "other_team": null
          }
        },
        "applications": [
          {
            "app_id": "FAAPPLI_Eg1dK5g",
            "sor_id": "SOR-SDK_2a116e0767a7dc76e85d566",
            "installations": [{
              "device_id": "01FF1D5F-41B0-4444-B145-E608BC45FFD1"
            }]
          }
        ]
      },
      {
        "customer_id": "robert.hill@mymail.org",
        "customer_id_type": "user_id",
        "attributes": {
          "global": {
            "first_name": "robert",
            "last_name": "hill",
            "email": "robert.hill@mymail.org",
            "date_of_birth": null,
            "gender": null,
            "country": null,
            "city": null,
            "region": null,
            "profile_picture_url": null
          },
          "SOR-SDK_2a116e0767a7dc76e85d566": {
            "favorite_team": "Real Madrid",
             "other_team": null
          }
        },
        "applications": [
          {
            "app_id": "FAAPPLI_Eg1dK5g",
            "sor_id": "SOR-SDK_2a116e0767a7dc76e85d566",
            "installations": [{
              "device_id": "FA3A11ED-200E-31DD-C409-430CBAE3204C"
            }]
          }
        ]
      }
    ]
  }
}

Status: 400

{
    "status": "400",
    "success": false,
    "error_message": "Param xxxxx is not valid"
}

View

GET /api/customer_profiles/customer_id?customer_id_type=type

This API retrieves the profile for a specific customer according the customer_id passed.

Query parameters

Property Type Description Default
customer_id string Customer id taken from the SOR.
If your customer id is an e-mail, for instance, don't forget to encode both the @ and . signs in the URL to ensure the APIs receive the full parameter, e.g. me@gmail.com becomes me%40gmail%2Ecom.
required
customer_id_type string Filter by the type of customer_id, user_id or device_id -
sor_identifiers string List of SOR identifiers separated by commas, used to define the Systems of Records to return for each profile in the output -
attribute_keys string List of attribute keys separated by commas, used to filter the SOR keys to return for each profile in the API output: only SORs containing a key matching this parameter will be returned, and only this key will be listed -

Response

Status: 200 OK

{
  "success": true,
  "result": [
    {
      "customer_id": "maximillian_weber@ritchiehyatt.name",
      "customer_id_type": "user_id",
      "attributes": {
        "global": {
          "first_name": "maximillian",
          "last_name": "weber",
          "email": null,
          "date_of_birth": null,
          "gender": null,
          "country": null,
          "city": null,
          "region": null,
          "profile_picture_url": null
        },
        "SOR-SDK_2a116e0767a7dc76e85d566": {
          "favorite_team": "PSG",
          "other_team": null
        }
      },
      "applications": [
        {
          "app_id": "FAAPPLI_Eg1dK5g",
          "sor_id": "SOR-SDK_2a116e0767a7dc76e85d566",
          "installations": [{
            "device_id": "01FF1D5F-41B0-4444-B145-E608BC45FFD1"
          }]
        }
      ]
    }
  ]
}

Feeding Customer Profiles with values

FollowAnalytics Ruby gem

We provide a ruby gem to help you modify values for profiles stored in FollowAnalytics.

Specific end-point

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.

Please use the end-point https://sor.follow-apps.com for this feature:

https://sor.follow-apps.com/api/attribute_values

Feeding a profile

POST /api/attribute_values

Body parameters

It takes a JSON object containing the following keys:

Property Type Description Default
sor string The System of Record identifier required
api_key string The API Key associated to this SOR required
customer_attribute_values array of objects An array of customer_attribute_value object (called CAV below to simplify reading) required
CAV[attribute_key] string The Attribute key. required
CAV[attribute_value] string The value of this attribute for this Customer. Possible values are listed below. required
CAV[customer_id] string The customer identifier required
CAV[action_type] string Used to ADD or REMOVE a specific value in an attribute of type Set. You can also use DEL to empty the set. required for Set attributes

Possible attribute values:

Value Type Description
Test string Limit of 256 Unicode characters
10 number Limit: 2**63 - 1
-1420.2 number Limit: -(2**63 - 1)
true boolean
false boolean
2016-12-22 date
2016-12-22T13:02:53Z datetime
null any Removes the value

If the Attribute is of type Set, you can delete a specific value by passing the parameter "action_type" : "REMOVE" or you can empty the Set for this user by passing : "action_type" : "DEL".

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" : "client_type",
            "attribute_value" : null
        },
        {
            "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" : "098713491",
            "attribute_key" : "fav_team",
            "attribute_value" : "France"
        },
        {
            "customer_id" : "098713492",
            "attribute_key" : "fav_team",
            "attribute_value" : "Italy"
        }
    ]
}

Response

The response will return the count of attributes uploaded along with the values that couldn't be set.

Status: 200 OK

{
    "success" : true,
    "result": {
        "uploaded" : 4,
        "unknown" : {
            "count" : 2,
            "keys" : ["fav_team"]
    }
}

Systems of Records

List

GET /api/system_of_records?type=type

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

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

Query parameter

Property Type Description Default
type string Filter results by type. Can be app, custom, or global. -

Response

Status: 200 OK

{
    "success": true,
    "result": [
        {
            "name": "Global SoR for Your Entity",
            "identifier": "SOR_id3nt1f13r",
            "type": "global",
            "api_keys": [
                "ebi97ujupC_tHQ"
            ],
            "attributes_count": 2,
            "disabled": false,
            "customer_attributes": [
                {
                    "disabled": false,
                    "identifier": "FACA_1518ddb56f2234933400dd0af9",
                    "key": "profit-focused-client-driven-standardization",
                    "label": "Smith and Sons",
                    "length": 50,
                    "predefined": true,
                    "shared": true,
                    "sources": [
                        "DEFAULT"
                    ],
                    "value_type": "String"
                },
                {
                    "disabled": false,
                    "identifier": "FACA_da6e51e7e4d8eb305f236a8977e6ab7c",
                    "key": "devolved-executive-matrices",
                    "label": "Schuppe, Zboncak and Mertz",
                    "length": 50,
                    "predefined": true,
                    "shared": true,
                    "sources": [
                        "DEFAULT"
                    ],
                    "value_type": "String"
                }
            ]
        },
        {
            "name": "SOR for app XYZ",
            "identifier": "SOR-SDK_your.package.name",
            "type": "app",
            "api_keys": [
                "FH7nIacl4f"
            ],
            "attributes_count": 0,
            "disabled": false,
            "customer_attributes": []
         }
    ]
}

View

GET /api/system_of_records/sor_identifier

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

Property Type Description Default
sor_identifier string The System of Records identifier to view required

Response

Status: 200 OK

{
    "success": true,
    "result": {
        "name": "Global SoR for Your Entity",
        "identifier": "SOR_id3nt1f13r",
        "type": "global",
        "api_keys": [
            "ebi97ujupC_tHQ"
        ],
        "attributes_count": 2,
        "disabled": false,
        "customer_attributes": [
            {
                "disabled": false,
                "identifier": "FACA_1518ddb56f2234933400dd0af9",
                "key": "profit-focused-client-driven-standardization",
                "label": "Smith and Sons",
                "length": 50,
                "predefined": true,
                "shared": true,
                "sources": [
                    "DEFAULT"
                ],
                "value_type": "String"
            },
            {
                "disabled": false,
                "identifier": "FACA_da6e51e7e4d8eb305f236a8977e6ab7c",
                "key": "devolved-executive-matrices",
                "label": "Schuppe, Zboncak and Mertz",
                "length": 50,
                "predefined": true,
                "shared": true,
                "sources": [
                    "DEFAULT"
                ],
                "value_type": "String"
            }
        ]
    }
}

Create

POST /api/system_of_records

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. Also, the global System of Record is always present, no need to create that either.

Body parameter

Property Type Description Default
name string Name of the new SOR required

Example

{
    "name": "My Custom SoR"
}

Response

Status: 200 OK

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

Update

PUT /api/system_of_records/sor_identifier

Modifies a System of Records.

Query parameter

Property Type Description Default
sor_identifier string The System of Records identifier required

Body parameter

Property Type Description Default
name string New name for the SOR required

Example

{
    "name": "My Custom SoR"
}

Response

Status: 200 OK

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

Delete

DELETE /api/system_of_records/sor_identifier

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.

Query parameter

Property Type Description Default
sor_identifier string Identifier for the SOR to delete required

Response

Status: 200 OK

{
    "success": true
}

Disable

PUT /api/system_of_records/sor_identifier/disable

Disables a System of Records.

Query parameter

Property Type Description Default
sor_identifier string Identifier of the SOR to disable required

Response

Status: 200 OK

{
    "success": true
}

Enable

PUT /api/system_of_records/sor_identifier/enable

Enables a System of Records.

Query parameter

Property Type Description Default
sor_identifier string Identifier of the SOR to enable required

Response

Status: 200 OK

{
    "success": true
}

Customer Attributes

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

View

GET /api/customer_attributes/ca_identifier

Gets information about a single customer attribute.

Query parameter

Property Type Description Default
ca_identifier string The Customer Attribute identifier required

Response

Status: 200 OK

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

Create

POST /api/customer_attributes

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

Body parameter

Property Type Description Default
system_of_record_identifier String The Customer Attribute related SOR required
key String The Customer Attribute key required
label String The Customer Attribute displayed name required
type String The Customer Attribute value type: String, Number, Boolean, Date, DateTime or Set required
length Integer The Customer Attribute length 256

Example

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

Response

Status: 200 OK

{
    "success": true,
    "result": {
        "identifier": "FACA_0OkzOc8",
        "key": "My Attr",
        "label": "my_attr",
        "value_type": "String",
        "length": 256,
        "predefined": false,
        "shared": null,
        "disabled": false
    }
}

Modify

PUT /api/customer_attributes/ca_identifier

Modifies a customer attribute.

Query parameter

Property Type Description Default
ca_identifier string The Customer Attribute identifier required

Example

{
    "label": "Test"
}

Response

Status: 200 OK

{
    "success": true,
    "result": {
        "identifier": "FACA_eVYy7KP9PZqP_B8w",
        "key": "is_valid",
        "label": "Test",
        "value_type": "Boolean",
        "length": 100,
        "predefined": false,
        "shared": false,
        "disabled": false,
        "system_of_record_identifier": "SOR-SDK_2a116e0767a7dc76e85a5ef85434d92b"
    }
}

Delete

DELETE /api/customer_attributes/ca_identifier

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.

Query parameter

Property Type Description Default
ca_identifier string The Customer Attribute identifier required

Response

Status: 200 OK

{
    "success": true
}

Share

PUT /api/customer_attributes/ca_identifier/share

A custom attribute can be moved from any SOR to the Global SOR: it becomes shared. It can also be unshared, and therefore be put back onto the SORs that sent data to it since it became shared.

When an attribute is shared, its key becomes reserved, and any SOR attempting to send data to that key will instead send the data to the Global SOR, on that common attribute.

As a result, when sharing an attribute from an SOR, all definitions on other SORs are shared as well. The user must be warned about this when sharing an attribute. Before this action is performed, we check the type of each attribute with the same key, and if there are conflicts, the attribute is not shared and an error message is returned to the user.

In addition, upon sharing, the new attribute in the Global SOR will automatically take a value. The value is calculated by taking the most recent of the values between all attributes with the same key. However, values from disabled attributes (see below) shall be ignored. In the edge case that all attributes are disabled, the new attribute in Global SoR will have no value. Otherwise, the new attribute will take a value and the timestamp of this action in the history will be the time of sharing.

Conversely, when unsharing an attribute, the definitions and values received so far for that shared attribute will be added back to the individual SORs using them. The attribute of the Global SoR is then deleted.

Query parameter

Property Type Description Default
ca_identifier string The Customer Attribute identifier required

Response

Status: 200 OK

{
    "success": true
}

Unshare

PUT /api/customer_attributes/ca_identifier/unshare

Unshares a customer attribute.

Only attributes from the global System of Records can be unshared. It is not possible to unshare a predefined attribute.

Query parameter

Property Type Description Default
ca_identifier string The Customer Attribute identifier required

Response

Status: 200 OK

{
    "success": true
}

Disable

PUT /api/customer_attributes/ca_identifier/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.

Attributes in the global SOR can be disabled or enabled as well. When disabling or enabling a global attribute, the status of the local attributes with the same key shall not change.

It is also possible to disable a local attribute that is shared. When disabling a local shared attribute, the corresponding global attribute remains enabled. This means that all values sent with the attribute’s key will be refused if they come from this specific SOR, but it is still possible to feed the global attribute from other SORs.

On the other hand, when enabling a disabled local shared attribute, the corresponding global attribute will be enabled as well. However, the status of all other local attributes with the same key in other SORs will not change.

It is not possible to disable predefined attributes.

Query parameter

Property Type Description Default
ca_identifier string The Customer Attribute identifier required

Response

Status: 200 OK

{
    "success": true
}

Enable

PUT /api/customer_attributes/ca_identifier/enable

Enables a previously disabled attribute.

Query parameter

Property Type Description Default
ca_identifier string The Customer Attribute identifier required

Response

Status: 200 OK

{
    "success": true
}