User Profiles

The User Profiles API allows to add data about your users that may come from your backend or any other external systems.

You can obtain your User Profiles upload API endpoint and credentials from your Pyze Account manager. This documentation will use https://import.pyze.com/users/profile as an example.

User Profile Attributes Object Specification

You can use this api to create or update any Pyze or custom attribute in the given user profile. Each request may include up to 50 profile fields.

FieldName Key Type Description Required
customer_id string Customer id for this user in your database, identifies a user uniquely Y
user_alias object Used to refer to users by their alias in some other third-party system {"alias_label": "","alias_id": ""} N
pyze_id string Pyze User ID N
Pyze User Profile Fields Varies Available fields N
my_custom_attribute Varies Available Types N

To remove a profile attribute, set it to null.

Custom Attributes

The following data types can be stored as a custom attribute:

Data Type Example Values
Boolean { "subscribed": true }
Strings {subscription_type: "Silver" }
Integer { "score": 30 }
Dates { "subscription_start": "2017-07-13T17:44:46Z" } Dates must be in ISO 8601 Format
Arrays { "categories": [ "electronics", "computers" ] }

Example call

POST https://import.pyze.com/users/profile
Content-Type: application/json
{
  "user_profiles":
      [
      	"customer_id": "user123",
	    "user_alias": {
	        "alias_label": "facebook",
	        "alias_id": "fb123409"
	    },
	    "first_name": "John",
	    "last_name": "Doe",
	    "date_of_first_use": "2016-04-12T17:27:20+00:00",
	    "date_of_birth": "1994-07-06",
	    "gender": "F",
	    "custom-ltv": 35,
	    "custom-purchase": {
	        "inc": 30
	    },
	    "custom-subscription": "premium",
	    "custom-tags": ["whale", "high-spender"]
    ],
    [
	    "pyze_id": "ca1ab028-185d-4833-a3af-5b5d46b62771",
	    "date_of_last_use": "2018-06-20T08:17:00+00:00",
	    "email_id": "jane.doe@gmail.com",
	    "custom-tags": {"remove" :['whale']}
    ]
}

Segments

You may create segements of known users via a file upload for use within Pyze analytics and campaigns.

You can obtain your Segments import API endpoint and credentials from your Pyze Account manager. This documentation will use https://import.pyze.com/segments/users as an example.

This API accepts an HTTP POST with a jsonl file attached.

Segments Import Object Specification

FieldName Key Description Required
segment_name This is the name of your new segment Y
file A file consisting of JSON lines of customer IDs as shown below Y

Segment File Format

The attached file should be formatted according to the standard JSON lines text file format, where the lines of the file are all valid JSON. Each line should be a dictionary with one key, one of customer_id, pyze_id, or user_alias as the value.

{"customer_id":"636b2a8907-78de-44a8-bcdb-7d3bc1b5232b"}
{"pyze_id":"aac6111a-6bef-470e-abe8-21397851e3ad"}
{"user_alias": {"alias_label": "facebook","alias_id": "fb123409" }}

Posting Events From Server to Pyze

Enterprise customers can also post event data to Pyze from their backend using a RESTful API.

The Pyze Enterprise Events API allows you to send events from your servers along with the data from your mobile and web apps. You can send these events at the same speed as the Pyze SDK’s and with the same level of detail.

The Pyze Enterprise Events API accepts HTTPS POST events. You can attach any custom attribute data to an event, and use this data throughout the Pyze system as attributes to filter and understand your users.

Endpoint

The url for all transactions is: https://import.pyze.com/v1/events

Content-Type HTTP Header should be application/json

Data Format

The Pyze Enterprise Events API accepts standard JSON documents with the following fields

FieldName Key Type Description Required
type string Type of the request message, events required
event string Name of the custom event required
userId strin Unique Identifier for the user required
eventTime string Timestamp when the event happened. ISO-8601 date string. optional
context object   optional
context.userAgent string User agent of users device optional
context.ip string Users current ip address optional
appKey string Pyze app key required
messageId string Unique identifier for each message optional
sentAt string Timestamp when the event is sent to Pyze, helps to correct clock skew. ISO-8601 date string optional
attributes object Key-Value pair. Additional properties about the event optional

Response

The Pyze Enterprise Events API will return a 202 response code if your event was properly formatted and accepted. The api will only validate if the overall format and validity of the JSON object, and if the request was properly Authenticated

202 Event has been accepted for processing
400 Not a valid input / “FieldName” is not provided
401 Not authorized to view
403 Need access to the provided app
500 Pyze internal server error. Please contact Pyze if problem persist

Example

A Curl Example:

curl -X POST -H "Content-Type: application/json" -d '{
    "type": "event",
    "event": "test-event",
    "userId": "mohan",
    "eventTime": "1234",
    "context": {
      "userAgent": "trial"
    },
    "appKey": "yz1Jn-0pSnekg58etEQO4A"
}' "https://import.pyze.com/v1/events"

Creating Apps Programmatically

Endpoint for bulk app creation

To create Apps Programmatically via an API, use the following endpoint. This endpoint is available to Pyze Enterprise Customers.

endpoint: https://e.pyze.com/api/apps
Request Type: POST
Content-Type: applicaiton/json
Authorization: HTTP Basic Authentication
JSON payload:  {
  "platform": "iOS",
  "appname": "My Awesome App",
  "appgroupids" : ["Uy1tWo8FQ7WvNMSrMf2a6A","Tz1tWo8FQ7WvNMSrMf2a6A"]
  "timezone": "America/Los_Angeles",
}

JSON payload Legend

  • “platform” is of string type and examples include: “iOS”, “Android”, “tvOS”, “Web”, “watchOS”
  • “appname” is of string type and is the name of your app
  • “appgroupids” is an optional array of App Group IDs, each of string type. You create App Groups at growth.pyze.com. Each App Group is associated with a unique appgroupid. “appgroupids” is optional and you can exclude it completely from the payload or specify as an empty array “appgroupids” : []
  • “timezone” is of string type and examples include “America/Los_Angeles”, “Asia/Kolkata” etc. It should be a valid timezone city name. Please see here for the Zone names (TZ) you can use.

Key and Secret

To locate your key and secret, please log in to growth.pyze.com and click on “Menu” from the main Portfolio screen.

Select API keys and secret.

Generate Key and Secret

Copy Key and Secret

CURL request example

For CURL, use your key and secret separated by a “:” to generate the basic authentication string. For example, if your key and secret are as follows,

  • Key: e5f2b490-9fbf-4bb2-91df-6105cf4c871b
  • Secret: 257040a4-998b-4379-8239-0977972c2a17

You can use a base 64 encoder to encode <key>:<Secret>:

e5f2b490-9fbf-4bb2-91df-6105cf4c871b:257040a4-998b-4379-8239-0977972c2a17

into a base64 basic authentication string:

ZTVmMmI0OTAtOWZiZi00YmIyLTkxZGYtNjEwNWNmNGM4NzFiOjI1NzA0MGE0LTk5OGItNDM3OS04MjM5LTA5Nzc5NzJjMmExNw== for use in a CURL request.

curl --request POST \
  --url https://e.pyze.com/api/apps \
  --header 'authorization: Basic ZTVmMmI0OTAtOWZiZi00YmIyLTkxZGYtNjEwNWNmNGM4NzFiOjI1NzA0MGE0LTk5OGItNDM3OS04MjM5LTA5Nzc5NzJjMmExNw==' \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/json' \
  --data '{"platform":"iOS","appname":"Application Name","timezone":"America/Los_Angeles"}'

Analytics Reporting API

Report API

  • Endpoint : https://api.pyze.com/report/getAnalytics
  • Authentication : Auth0 URL
  • Content-Type: Application/JSON
  • Rate Limits : As Applicable per customer

Request Format:

{
  "pyzeAppKey" : string,
  "appGroupId" : string,
  "startTime" : string,
  "endTime" : string,
  "metric" :  string, 
  "aggregation" : string, 
  "filter" : string, 
  "timeType" : enum(TimeType),
}

Sample Response:

Sample Response for Activations (Metric) during the 3rd Session (Metric Filter) in the app aggregated by the os_version (Aggregation)

{
   "result":{
      "metric" : "activations",
      "aggregation" : "os_version",
      "filter" : "session_3rd",
      "metric-aggregation":[
         {
            "k":"Android 6.x",
            "v":[
               {
                  "k":"1506297600000",
                  "count":1
               },
               {
                  "k":"1506902400000",
                  "count":4
               }
            ]
         },
         {
            "k":"Mac OS X (iPhone)",
            "v":[
               {
                  "k":"1505692800000",
                  "v":1
               },
               {
                  "k":"1506902400000",
                  "v":2
               }
            ]
         }
      ]
   }
}

Error/Status codes:

  • 200 Request succeded
  • 400 Not a valid input / “FieldName” is not provided
  • 401 Not authorized to view
  • 403 Need access to the provided app/appgroup
  • 500 Pyze internal server error. Please contact Pyze if problem persists

Additional notes

  • Reports will be presented in GMT epoch
  • Only a valid combination of filter can be queried with a certain metric.

Fields, Types and Conditions

Field Type Conditions
pyzeAppKey String Either pyzeAppKey or appGroupId is required. If both are present appGrouId will take precedence
appGroupId String Either pyzeAppKey or appGroupId is required. If both are present appGrouId will take precedence
startTime String Required : UTC milliseconds since epoch. Eg: 1513393084000 - based on the GMT timezone . If start and end time are not specified , will default to last 7 days
endTime String Required : UTC milliseconds since epoch. Eg: 1513393084000 - based on the GMT timezone . If start and end time are not specified , will default to last 7 days
timeType String enum TimeType(DAY , WEEK, MONTH). Will Default to DAY
metric String Required e.g.: Installs, Activations
aggregation String Optional Eg: Carrier, Browser
filter String Metric or Aggregation filter e.g.: activations:session_3rd (metric filter) or browser:chrome (aggregation filter)

Available Metrics, Aggregations and Filters

Metric Aggregation Metric Filter
installs Mobile & Web Analytics:
device_manufacturer
device_product
device_platform
device_resolution
country
locale_language
os_version
Mobile Analytics only:
device_pixels_per_inch
cellular_capability
reachability
app_version
Web Analytics only:
browser
utm_campaign
utm_medium
utm_source
cookie
browser_plugin
None
activations Mobile & Web Analytics:
device_manufacturer
device_product
device_platform
device_resolution
country
locale_language
os_version
Mobile Analytics only:
device_pixels_per_inch
cellular_capability
reachability
app_version
Web Analytics only:
browser
utm_campaign
utm_medium
utm_source
cookie
browser_plugin
session_3rd
session_5th
session_10th
first_time_app_used_for_2_days_in_last_7_day_period
first_time_app_used_for_3_days_in_last_7_day_period
first_time_app_used_for_3_unique_days
first_time_app_used_for_5_unique_days
first_time_app_used_for_7_unique_days
aggregate_usage_exceeds_15_min
aggregate_usage_exceeds_30_min
aggregate_usage_exceeds_60_min
previous_consecutive_3_day_usage_exceeds_5_min
previous_consecutive_3_day_usage_exceeds_10_min
previous_consecutive_3_day_usage_exceeds_15_min
previous_consecutive_3_day_usage_exceeds_30_min
previous_consecutive_5_day_usage_exceeds_5_min
previous_consecutive_5_day_usage_exceeds_10_min
previous_consecutive_5_day_usage_exceeds_15_min
previous_consecutive_5_day_usage_exceeds_30_min
previous_consecutive_7_day_usage_exceeds_5_min
previous_consecutive_7_day_usage_exceeds_10_min
previous_consecutive_7_day_usage_exceeds_15_min
previous_consecutive_7_day_usage_exceeds_30_min
average_daily_usage_per_device Mobile & Web Analytics
device_manufacturer
device_product
device_platform
device_resolution
country
locale_language
os_version
Mobile Analytics only:
device_pixels_per_inch
cellular_capability
reachability
app_version
Web Analytics only:
browser
utm_campaign
utm_medium
utm_source
cookie
browser_plugin
None
average_app_sessions_per_device Mobile & Web Analytics:
device_manufacturer
device_product
device_platform
device_resolution
country
locale_language
os_version
Mobile Analytics only:
device_pixels_per_inch
cellular_capability
reachability
app_version
Web Analytics only:
browser
utm_campaign
utm_medium
utm_source
cookie
browser_plugin
None
daily_active_devices Mobile & Web Analytics:
device_manufacturer
device_product
device_platform
device_resolution
country
locale_language
os_version
Mobile Analytics only:
device_pixels_per_inch
cellular_capability
reachability
app_version
Web Analytics only:
browser
utm_campaign
utm_medium
utm_source
cookie
browser_plugin
None
retention Mobile & Web Analytics:
device_manufacturer
device_product
device_platform
device_resolution
country
locale_language
os_version
Mobile Analytics only:
device_pixels_per_inch
cellular_capability
reachability
app_version
Web Analytics only:
browser
utm_campaign
utm_medium
utm_source
cookie
browser_plugin
d1_retained
d2_retained
d3_retained
d4_retained
d5_retained
d6_retained
d7_retained
d8_retained
d9_retained
d10_retained
d11_retained
d12_retained
d14_retained
d30_retained
event_occurance None Event Name configured in the app along with Pyze generated events
event_popularity None None
event_attribute_popularity Pyze Attributes
device_manufacturer
device_product
device_platform
device_display_inches
device_display_pixel_HxW
carrier
os_version
locale_region
locale_language
locale_calendar.
Application Attributes
Event Name configured in the app along with Pyze generated events
engagement_to_interaction_app_screen None None
interactions None None