Follow

Logs API for User Merge

Logs API for User Merge

This REST API enables you to download records that contain information about user merges. Kahuna performs user merges to keep accurate information for a single user. The merge cleans up your user information by detecting and combining data that is for the same actual person. Kahuna detects duplicate data for the same person when it receives an event from your app; if the user credential values sent from the app match more than one user record, Kahuna merges the two records. The merged information goes into the user record with an older creation date. The merged record contains the user credentials the two records had in common, as well as all of their unique user credentials. Kahuna deletes the newer record.

Kahuna logs the merge in a record that contains the unique credentials from the two records as well as the common credentials that led to the merge. Even though Kahuna merges all of the data in the two records, the log record only contains the credentials data.

API Request

Request URI and Header

Request URI - HTTP POST

To target the production environment: https://tap-nexus.appspot.com/api/kahunalogs?env=p

To target the sandbox environment: https://tap-nexus.appspot.com/api/kahunalogs?env=s

Request Header

Content-Type: application/json

Authorization: The API uses Basic Authentication (BasicAuth), which requires credentials in the form of a username (Secret Key) and password (API Key).

The Secret Key and API Key for the namespace are:

Secret Key: Available in Settings
API Key: Available in Settings
Request Body

The request body contains data that controls which log records the server returns. The fields are described below.

Fields
timestamp

Note: You must specify either timestamp or cursor; otherwise, the server returns a 400 HTTP response code.

The server returns records for the date specified in the timestamp. For this date, the returned records have a timestamp starting at the specified time and ending on or before 23:59:59 of the specified date. Although most known date and time formats work, you can always use the format:

m/dd/yyyy h:mm

Elements in bold are entered exactly as written.

  • m is the month number (1 or 2 digits)
  • d is the day number (1 or 2 digits)
  • yyyy is the four-digit year
  • h is the hour in 12-hour format
  • mm is minute

You must convert the time to its UTC equivalent. All Kahuna timestamps are stored in UTC. The API does not convert the timestamp value to UTC before comparing it to log records.

cursor

Note: You must specify either timestamp or cursor; otherwise, the server returns a 400 HTTP response code.

This is the identifier of a previously returned cursor. Cursor identifiers are temporary and can expire at any time. See Response Body, below.

number_of_records Required. The number of records to retrieve. The number must be greater than 0 and less than or equal to 1000.
categories_to_return

Required.

For email logs, set "categories_to_return" : ["email"]

For push logs, set "categories_to_return" : ["push"]

For in-app messages, set "categories_to_return" : ["inapp"]

For user merge logs, set "categories_to_return": ["user_merge"].

You can retrieve other categories except for user_merge in the same request by adding their categories to the array. However, you cannot combine the user_merge category with other categories.

Example
{
    "number_of_records" : 1000,
    "timestamp" : "07/30/2016 00:00",
    "categories_to_return" : [ "user_merge" ]
}

API Response

Kahuna responds to a logs request with a numeric code and a response body.

HTTP Response Codes

The HTTP response code returned from a request indicates the overall status of the request.

Codes
200 Successful API call.
400

Bad request. Some part of the request is malformed. For example, the specified number of records is invalid.

401

Authentication or authorization failure. The credentials supplied with the request are invalid.

409 Not authorized. The credentials are not authorized to use the Logs API.
500 Kahuna internal server error.
Response Body

The response body is a JSON object that contains additional information about the status of the request, as well as an array of log records. If the server cannot deliver all the records that match your request in a single response, the response body contains two fields in addition to the array of log records:

  • more_records is a boolean value that is set to true if more records are on the server.
  • cursor is a string value that points to the set of remaining records.

To continue retrieving records for your original request, add the value of cursor in the request body and send a new request. The server responds with a new set of records. This process continues until one of these conditions is met:

  • The server has sent all the records that match the day you specified in the timestamp field in the request body.
  • The number of records sent is equal to the value of number_of_records you specified in the request body.
  • You stop sending log requests containing the value of cursor returned to you in the response body.

The fields in the response body and individual log records are listed below.

Fields
success

If the request fails, this field is set to false. If the request succeeds, this field is not present.

error

If an error occurs, provides a human-readable error message. If no error occurs, this field is not present.

error_code

If an error occurs, provides the HTTP error code. If no error occurs, this field is not present.

error_detail

If an error occurs, provides more detailed information about the error. If no error occurs, this field is not present.

more_records

If more records are available for download this field is set to true; otherwise the field is set to false.

cursor

If the server cannot deliver all the records that match your request in its initial response, it sets more_records to true and returns a cursor value that points to more records on the server. To retrieve these records, move the value of cursor to the cursor field in the request body and re-issue the request.

user_merge

An array of JSON objects representing the log records. If the request is well-formed, but no records match the time and date criteria, the array is empty. The format of the individual record is:

source user

An object that contains information about the source user record from which Kahuna copied data. This record was the newer of the two records that had user credentials in common.

This object always contains the field user_id, which is the Kahuna-assigned globally-unique user identifier (GUID) for the newer user record. When Kahuna does a user merge, it copies data from this record to the older record.

This object may contain the field credentials, which is an array of credentials in the newer user record that were not in the older user record. During the merge, these credentials are copied to the older record.

destination_user

An object that contains information about the destination user record to which Kahuna copied data. This record was the older of the two records that had user credentials in common.

This object always contains the field user_id, which is the Kahuna-assigned globally-unique user identifier (GUID) for the older user record. When Kahuna does a user merge, it copies data to this record from the newer record.

This object may contain the field credentials, which is an array of credentials in the older user record that were not in the newer user record. These credentials remain in the destination record.

common_credentials

An array containing user credential strings where each string has the format key_text:value_text where key_text contains one of the possible credential key values, and value_text contains the actual value for that key. These common credentials are the reason the user merge occurred.

Example

In this JSON snippet, the first element of common_credentials is email:georgew@example.com. Its key_part is email and its value_part is georgew@example.com.

"common_credentials": [
    "email:georgew@example.com",
    "username:George Washington"
]
timestamp

The date and time the record was created. The format is YYYY-MM-DD HH:MM:SS.SSSSSS. The time is UTC.

Note: The timestamp format that you use in your REST request does not have to match the format in the log record.

Example

The following JSON snippet shows the first part of a user merge response body.

{
"more_records": true,
"cursor": "_NJXWEX2WGZBS24KQJNMEMM2XIN2GSRTFGFGGS2KTMJYWWNCGIE______
        _INEUGUSCIFCUCUKBINJFKQSBJFBESSKBKVEUMUKWLFFVCPJ5HU6Q____",
"user_merge": [
    {
        ...

The following JSON snippet shows an example of user merge records.

"user_merge": [
    {
        "source_user": {
            "user_id": 49630002
        },
        "timestamp": "2015-09-01 23:41:24.731020",
        "common_credentials": [
            "email:george@example.com",
            "username:george"
        ],
        "destination_user": {
            "credentials": [
                "email:george.washington@example.com",
                "username:george.washington@example.com",
                "token:APA91bHxDVpVtcr6tsTD5XCJL1RYlAwn"
            ],
            "user_id": 22880005
        }
    },
    {
        "source_user": {
            "user_id": 51300003
        },
        "timestamp": "2015-09-01 23:47:42.291750",
        "common_credentials": [
            "email:james@example.com",
            "username:james"
        ],
        "destination_user": {
            "credentials": [
                "token:639dabaa02cca58af7ad7bb09891b99ec1959a998f935f513ae05a9c0b207c48",
                "email:james.madison@example.com",
                "email:jamesmadison@kahuna.com",
                "username:james madison",
            ],
            "user_id": 1340001
        }
    }
]
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments