PushizoDocs
Users & segments

Users, aliases and subscriptions

The Pushizo identity model — end users, external_id and custom aliases, subscriptions (device, email, phone), tags/properties/deltas, anonymous → identified merging, events and public API endpoints.

In Pushizo, a user (usr_…) is your end user; a user can have multiple subscriptions (sub_…): an iOS/Android/Huawei device token, a browser subscription, an email address, a phone number, a WhatsApp/RCS number. Users are addressed by aliases: external_id (your ID), hs_id (the Pushizo ID) and custom labels such as crm_id.

User usr_01J…  ── alias: external_id=user_42, crm_id=C-9 ── tags {plan: pro}, properties {city: İzmir}
   ├─ sub_… ios_push     (token, device, language, time zone, permission)
   ├─ sub_… web_push     (endpoint + keys)
   ├─ sub_… email        ayse@pushizo.com
   └─ sub_… sms          +905321234567

From anonymous to identified

On launch, the client SDK creates an anonymous user and a device subscription. When login(externalId) is called, the subscription is linked to the user with that external_id; if no such user exists, the anonymous record gains the identity, and if one exists, the anonymous user is merged into it (tags/properties/preferences are merged and a user.merged webhook is emitted). logout() detaches the device to a new anonymous user. When multiple devices log in with the same external_id, they are gathered under a single user.

If identity verification is required in the app settings, login is accepted only with an identity_hash = HMAC-SHA256(sdk_secret, external_id) or an ES256 JWT generated by your server (JWT identity verification).

Tags, properties, deltas

DataTypeUsage
tagsRecord<string, string> (merge-patch; null deletes)Segment conditions, Liquid ({{ user.tags.plan }})
propertiesRecord<string, string | number | boolean> (merge-patch)Typed fields, segment comparisons
deltas{ session_count?, session_time?, purchases?[] }Counters compatible with the legacy provider (PATCH only)
languageISO 639-1Content selection from language maps (contents.tr)
timezoneIANATime-zone-based delivery
locationlatitude/longitude (with consent)Radius segments (location)

A tag key can be at most 64 characters and a value at most 500; the number of tags per user is subject to the plan quota.

Public API

OperationEndpointScope
Create/update (upsert)POST /v1/apps/{app_id}/users { identity: { external_id, … }, tags, properties, subscriptions[] } — Idempotency-Key is supportedusers:write
Read by aliasGET /v1/apps/{app_id}/users/by/{label}/{value} (external_id, hs_id or a custom label)users:read
Tags/properties/deltasPATCH /v1/apps/{app_id}/users/by/{label}/{value}users:write
Add / remove aliasPATCH …/identity { identity: { crm_id: "C-9" } }, DELETE …/identity/{alias_label}users:write
All identitiesGET …/identityusers:read
Add subscriptionPOST …/subscriptions { channel, token, device?, opt_in? }users:write
Read/update/delete subscription`GETPATCH
Assign ownerPOST …/subscriptions/{id}/owner { external_id }users:write
List / searchGET /v1/apps/{app_id}/users?q=&tag=&last_active_after=&sort=; POST …/users/search (segment definition)users:read
Export (KVKK)GET …/export → profile, aliases, subscriptions, recent eventsusers:read
Delete (KVKK)DELETE /v1/apps/{app_id}/users/by/{label}/{value} → subscriptions are deleted, events are anonymizedusers:write
Send eventsPOST /v1/apps/{app_id}/events { events: [{ external_id, name, properties?, value?, timestamp? }] }events:write

All fields, response schemas and examples in 8 languages: API → Users and subscriptions, event definitions. Dashboard: Audience → Users (search, segment filter, user detail: subscriptions, timeline, notification inbox, preferences).

Subscription statuses

active (sendable), pending (awaiting permission), unsubscribed (opt-out, STOP, one-click), invalid (rejected by the provider: 410, bounce). invalid subscriptions become active again on re-registration; unsubscribed is reopened only by a user action (optIn, START, preferences) or by a PATCH with opt_in: true. Status changes emit subscription.created|unsubscribed|invalidated webhooks.

Events and conversions

Pushizo.Session.sendEvent('purchase', { sku: 'A1' }, 49.9) or POST /v1/apps/{app_id}/events. Event definitions (GET /v1/apps/{app_id}/events/definitions) track the name, first/last seen and 30-day count; events marked is_conversion via PATCH …/definitions/{name} are attributed as conversions within the window after a message click (direct_click / influenced). Events feed segment conditions as well as journey and in-app triggers.

Bulk import/export

For bulk user/subscription upload via CSV (csv_users) and the legacy provider's player CSV (legacy_players), see exports/imports; imports do not emit webhooks.

On this page