User Attribute Upload API

The Ptengine API allows you to bulk upload user attribute data to Ptengine for use in user segmentation analysis and other features.

The API is built on REST architecture, accepts JSON-formatted request bodies, and returns JSON-encoded responses.

---

1. Authentication

Obtaining an API Key

Obtain or create a new API key from the "Integration" page in Ptengine.

API keys are issued at the project level. Each project requires its own API key.

Protecting Your API Key

API keys are confidential. Do not expose them in client-side code such as browsers or mobile apps. Route production requests through your backend server and load keys securely from environment variables or a key management service.

All API requests must include the API key in the HTTP header:

Authorization: Bearer PTENGINE_API_KEY

---

2. API Specification

Item	Details
API URL	https://api.ptengine.com/v1/user/profiles
Protocol	HTTPS
Method	POST
Data Format	JSON

A single request can upload up to 100 users with their attribute data.

---

3. Request Body

The request body contains two fields:

Field	Type	Required	Description	Limits
field_name	String[]	Yes	Array of attribute key names. Must include user_id	Maximum 50 fields, each name up to 50 characters
values	Array[]	Yes	Two-dimensional array of user attribute values. The order must correspond to field_name. Use "" for empty values	Maximum 100 users, each value up to 128 characters

---

4. Update Policy

Each request must include user_id (a unique user identifier). Ptengine uses user_id to check whether the user already exists and processes accordingly:

User Status	Attribute Status	Update Policy
Exists	Exists	Updates the existing attributes
Exists	Does not exist	Creates new attributes for the user
Does not exist	/	Creates a new user and their attributes

---

5. Request Example

Suppose you want to upload the following user attributes:

user_id	watch_conan	watch_attack_on_titan
abcd123	yes	no
abcd456	yes	yes
abcd789	no	no

The request body would be:

{
  "field_name": [
    "user_id",
    "watch_conan",
    "watch_attack_on_titan"
  ],
  "values": [
    ["abcd123", "yes", "no"],
    ["abcd456", "yes", "yes"],
    ["abcd789", "no", "no"]
  ]
}

The order of values must match the order of field_name.

---

6. Code Examples

Replace <API_KEY> with your actual API key before sending requests.

Python

import requests
import json

url = "https://api.ptengine.com/v1/user/profiles"

payload = json.dumps({
  "field_name": [
    "user_id",
    "watch_conan",
    "watch_attack_on_titan"
  ],
  "values": [
    ["abcd123", "yes", "no"],
    ["abcd456", "yes", "yes"],
    ["abcd789", "no", "no"]
  ]
})
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer <API_KEY>'
}

response = requests.post(url, headers=headers, data=payload)
print(response.json())

Node.js

const axios = require('axios');
let data = JSON.stringify({
  "field_name": [
    "user_id",
    "watch_conan",
    "watch_attack_on_titan"
  ],
  "values": [
    ["abcd123", "yes", "no"],
    ["abcd456", "yes", "yes"],
    ["abcd789", "no", "no"]
  ]
});

let config = {
  method: 'post',
  url: 'https://api.ptengine.com/v1/user/profiles',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer <API_KEY>'
  },
  data: data
};

axios(config)
  .then(response => console.log(response.data))
  .catch(error => console.log(error));

PHP

<?php
$client = new Client();
$headers = [
  'Content-Type' => 'application/json',
  'Authorization' => 'Bearer <API_KEY>'
];
$body = '{
  "field_name": ["user_id", "watch_conan", "watch_attack_on_titan"],
  "values": [
    ["abcd123", "yes", "no"],
    ["abcd456", "yes", "yes"],
    ["abcd789", "no", "no"]
  ]
}';
$request = new Request('POST', 'https://api.ptengine.com/v1/user/profiles', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

Java

OkHttpClient client = new OkHttpClient().newBuilder().build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType,
  "{\"field_name\":[\"user_id\",\"watch_conan\",\"watch_attack_on_titan\"],"
  + "\"values\":[[\"abcd123\",\"yes\",\"no\"],"
  + "[\"abcd456\",\"yes\",\"yes\"],"
  + "[\"abcd789\",\"no\",\"no\"]]}");
Request request = new Request.Builder()
  .url("https://api.ptengine.com/v1/user/profiles")
  .method("POST", body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Authorization", "Bearer <API_KEY>")
  .build();
Response response = client.newCall(request).execute();

Go

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {
  url := "https://api.ptengine.com/v1/user/profiles"
  payload := strings.NewReader(`{
    "field_name": ["user_id", "watch_conan", "watch_attack_on_titan"],
    "values": [
      ["abcd123", "yes", "no"],
      ["abcd456", "yes", "yes"],
      ["abcd789", "no", "no"]
    ]
  }`)

  req, _ := http.NewRequest("POST", url, payload)
  req.Header.Add("Content-Type", "application/json")
  req.Header.Add("Authorization", "Bearer <API_KEY>")

  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)
  fmt.Println(string(body))
}

---

7. Response

Success

HTTP status code 200 OK

{
  "msg": "Success",
  "timestamp": 1684155980
}

Failure

HTTP status code varies by error type.

{
  "msg": "The reason for the request failure",
  "timestamp": 1684155980
}

Status Code Reference

HTTP Status	Description
200 (OK)	Request was successful
400 (Bad Request)	Request could not be accepted. Likely missing required parameters (e.g., field_name does not include user_id)
401 (Unauthorized)	API key is invalid or incorrect
403 (Forbidden)	API key does not have the appropriate permissions for this request
404 (Not Found)	The requested resource does not exist or the URL is incorrect
500/502/503/504	An issue occurred on the Ptengine server

---

8. Uploading Large Datasets

A single request can upload a maximum of 100 users. If you have more than 100 users, split the data into batches of 100 and send multiple requests.

For example, to upload data for 600 users, split it into 6 requests of 100 users each.