Follow

User Attribute API

User Attribute API

This REST API enables you to add, update, or delete information for existing users (user attributes). In the Kahuna system, user attributes are important for campaign filtering, personalizing information, and deep-linking. Information such as age, gender, or region helps you target users you want to reach with a particular campaign. Information such as name, birthday, and address helps you send personalized push notifications or email messages as part of your campaign. Information such as purchase dates, products used, or personal interests helps you create individualized deep links, which you can send within a push notification or email.

Note: Kahuna allows a maximum of 100 users per request.

API Request

Request URI and Header

Request URI - HTTP POST

 

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

To target the sandbox environment: https://tap-nexus.appspot.com/api/userattributes?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 is a JSON object that contains an array of users and the attributes that you want to add or update for the user.

In the request body, users and attributes are formatted as an array with the field name user_attributes_array. Each element of this array contains a dictionary of credentials that identify a user and a dictionary of attributes to apply to that user. Each element is known as a User Attribute object. Even if you are only updating one user, you have to specify the user and attributes in a User Attribute object in a one-element user_attributes_array.

The following table describes the User Attribute object format.

Fields
target

Required. The dictionary of user credential key-value pairs.

  • Each key must be a Kahuna white-listed user credential type.
  • You can specify as many credentials as you want, but the servers select a user based on the first match between a credential in the dictionary and a user credential on the servers.
attributes

Required. The dictionary of user attribute key-value pairs.

  • You can specify an attribute value as a string, integer, or boolean. Enclose string values in quotes. If you enclose a numeric or boolean value in quotes, it is treated as a string.
  • You must enclose dates and times in quotes and use ISO format. For example, "2006/03/21 00:00"
  • To update a user attribute, specify an existing key with a new value.
  • To delete a user attribute, set its value to null.
  • The size of an individual user attribute value is limited to 2048 bytes.
Example
{
    "user_attributes_array": [
        {
            "target": {
                "email": "george@example.com",
                "username": "george0000"
            },
            "attributes": {
                "first_name": "George",
                "last_name": "Washington",
                "gender": "m",
                "age": 44,
                "language": "en"
            }
        },
        {
            "target": {
                "email": "john@example.com",
                "username": "john0002"
            },
            "attributes": {
                "first_name": "John",
                "last_name": "Adams",
                "birth_date": "1995/03/21"
            }
        }
    ]
}

API Response

The response to a User Attributes API request consists of an HTTP response code and a response body in JSON format.

HTTP Response Codes
Codes
200

The servers successfully parsed the request, and authentication and authorization also succeeded.

Note: This response code is returned even if all the update requests fail. For example, this response code is returned if parsing and authentication or authorization succeed but the servers are unable to find any of the specified users.

400 Parsing error. You specified invalid options or the JSON is written incorrectly. The response body provides error details.
401 Authentication error. Your credentials are written incorrectly or your credentials are not valid. The response body provides error details.
409 Authorization error. Your user name and password are authorized for Kahuna but you do not have permission to use the User Attributes API.
500 Kahuna internal server error.
Response Body

The response body is an array that contains one or more response object elements, depending on the HTTP response code:

  • HTTP response code 200—the array contains an element for each User Attribute object in the request body. The response objects have the same order as the User Attribute objects in the request body.
  • HTTP response codes 400, 401, 409, and 500—the array contains a single response object that provides additional information about the error.

Note: If the HTTP response code is not 200, the response object represents the status of the overall request instead of the status of the request for an individual user.

Response Object

The format of a response object is shown in the following table.

Fields
success

The status of the attribute update for the user. If true, the request succeeded. No other fields are present in the response object. If false, the request failed. Other fields in the response object provide additional information about the failure.

error

If an error occurred, this field provides a human-readable error message.

error_code

If an error occurred, this field provides an HTTP error code. Error code 404 indicates that the servers cannot find the user given the supplied credentials. This code is not returned in the overall HTTP response code.

Example
{
   "user_attributes_array": [
        {
            "target": {
                "email": "george@example.com",
                "username": "george0000"
            },
            "attributes": {
                "first_name": "George",
                "last_name": "Washington",
                "gender": "m",
                "age": "44",
                "language": "en"
            }
        },
        {
           "target": {
                    "email": "tom@example.com",
                    "username": "tom0002"
            },
            "attributes": {
               "first_name": "Tom",
               "last_name": "Sawyer"
            }
        }
    ]
}
 

If the user credential "email": "george@example.com" points to an existing user, but the user credential "email": "tom@example.com" does not, then the HTTP response code is 200 and the response body contains the following JSON:

[
    {
        "success": true
    },
    {
        "success":false,
        "error_code":404,
        "error": "User not found"
    }
]
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments