Skip to main content

​
Identity

Identities are aggregations of contacts in the Plati AI system. They group multiple contact points (phone numbers, emails, etc.) under a single user identity, enabling personalized conversations, memory persistence, and stage tracking across all channels.

​
List Identities

GET /identity

Returns a list of all identities in your workspace.

​
Query Parameters

​
number
Page number for pagination
​
number
Number of items per page

​
Get Identity

GET /identity/:identity_id

Returns detailed information about a specific identity.
​
:identity_id
string
required
Identity unique identifier

​
Response

​
message
string
Success message
​
data
object

​
Create or Update Identity

PUT /identity/:identity_id

Creates a new identity or updates an existing one. If the identity exists, it will be updated; otherwise, a new one will be created.
​
:identity_id
string
required
Identity unique identifier (can be external_id or generated UUID)

​
Request Body

​
string
Name of the identity
​
string
Phone number (E.164 format recommended)
​
string
Email address
​
string
External identifier from your system
​
object
Custom metadata object

​
Delete Identity

DELETE /identity/:identity_id

Deletes an identity and all associated data (conversations, memory, stages).
​
:identity_id
string
required
Identity unique identifier

​
Update Identity Stage

POST /identity/:identity_id/stage

Updates the current stage of an identity, tracking their journey through your system.
​
:identity_id
string
required
Identity unique identifier

​
Request Body

​
string
required
Stage unique identifier
​
object
Additional metadata for the stage transition

​
Identity-First Architecture

The Plati AI platform uses an identity-first architecture, meaning:
  1. Identity Aggregates Contacts - An identity groups multiple contacts (phone numbers, emails, etc.) into a single user profile
  2. One Identity, Multiple Channels - A single identity can interact across WhatsApp, web, mobile, etc.
  3. Persistent Memory - All conversations and context are tied to the identity
  4. Stage Tracking - Track where users are in their journey
  5. Unified Profile - Single source of truth for user data across all contact points

​
Identity Identifiers

Identities can be identified by:
  • Internal ID - Generated UUID by Plati AI
  • External ID - Your system’s identifier
  • Phone Number - For WhatsApp and SMS channels
  • Email - For email channels

​
Examples

​
Get Identity

curl -X GET https://api.plati.ai/identity/abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Create/Update Identity

curl -X PUT https://api.plati.ai/identity/user_12345 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "phone": "+5511999999999",
    "email": "[email protected]",
    "external_id": "user_12345",
    "metadata": {
      "plan": "premium",
      "signup_date": "2024-01-15"
    }
  }'

​
Update Stage

curl -X POST https://api.plati.ai/identity/user_12345/stage \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "stage_id": "onboarding_complete",
    "metadata": {
      "completed_at": "2024-01-20T10:30:00Z"
    }
  }'

​
Delete Identity

curl -X DELETE https://api.plati.ai/identity/user_12345 \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Next Steps

Memory

Access identity memory

Stages

Manage user journey stages

Conversations

Start conversations with identities

Core Concepts

Learn about identity-first architecture