Best Practices for Implementing User Profiles in API Systems

Gabe · 2025-11-06T18:07:06.658Z

We are on the original api, and do not have users implemented. Within our app, users have the ability to have multiple profiles, including single solo and partner profiles, but all unique users are tied to an account with a unique account id per valid phone number used in registration. What would be the best practice for properly implementing users including setting the distinct id, managing profile identity for users (maybe tying distinct id to account id and passing in an active profile id as a user property?), when we should be identifying users and resetting them (log in, sign up, log out, etc.), and setting user/profile properties when profile information is updated, etc?

kapa.ai
APP
·
·
Hi Gabe, Please stand by as I search the Mixpanel knowledge base for an AI-powered answer. I normally take about 15 seconds or so. In case AI cannot answer your question, feel free to reach out to Mixpanel support at mixpanel.com/get-support. If you have follow-up questions for this thread, please tag me again with your question: @kapa.ai <follow-up question> 👋
Feel free to ask a follow-up question once I've answered by mentioning me with @kapa.ai
kapa.ai
APP
·
·
Given your scenario—using the Original API, no users currently implemented, and each unique user tied to an account ID (per phone number), with the ability for each account to have multiple profiles (solo/partner)—here are the best practices for implementing user identity and profile management in Mixpanel:
1. Setting the distinct_id
- Use the unique account ID (tied to the phone number) as the distinct_id for each user. This ensures that all activity for a given account is attributed to a single user in Mixpanel. - For anonymous users (before registration or login), let the Mixpanel SDK generate a $device_id and use that as the distinct_id until the user registers or logs in. Learn more
2. Managing Profile Identity
- Active Profile ID as a User Property: Since each account can have multiple profiles (solo/partner), pass the currently active profile ID as a user property (e.g., active_profile_id) on all events. This allows you to segment and analyze events by which profile was active at the time. - Do not use the profile ID as the distinct_id—this would fragment the user’s activity across multiple Mixpanel users, making it difficult to get a unified view of the account.
3. When to Identify and Reset
- Call .identify(account_id): - On registration (sign up) - On login - When the app is re-opened in a logged-in state This links all pre-login (anonymous) activity to the account and ensures all future events are attributed to the correct user cluster. - Call .reset(): - On logout - When there is an explicit intent to switch to a new user (e.g., clicking "Sign-up" for a new account on the same device) This clears the current user’s identity and generates a new $device_id for the next session, preventing data from different users from being merged. Best practices
4. Setting User/Profile Properties
- Set user properties (e.g., account-level info) after identification using .people.set() or equivalent, and always after the user is identified. - Set profile properties (e.g., profile name, type, etc.) as event properties or as user properties (if you want to persist them on the user profile) whenever the active profile changes or is updated. - Avoid creating profiles for anonymous users. Only set user/profile properties after the user is identified. More details
5. Example Flow
1. Anonymous User: - Events tracked with SDK-generated $device_id as distinct_id. 2. User Registers/Logs In: - Call .identify(account_id). - All future events use account_id as distinct_id. - Set user properties (e.g., phone number, registration date). 3. User Switches Profile: - Pass active_profile_id as an event/user property on all events. - If profile info changes, update relevant properties. 4. User Logs Out: - Call .reset() to clear identity and generate a new $device_id for the next session.
6. Additional Best Practices
- Track the account ID as a super property and user property to assist with troubleshooting and querying. - QA your implementation to ensure no duplicate profiles and that all identifiers are correctly clustered. - Document your ID management approach for future reference and troubleshooting. Best practices summary
If you need to merge two account IDs (e.g., in rare cases of account consolidation), you can use the $merge API event, but this is not typical for most flows and should be used with caution.
References: - Original API: Best Practices - Identity Management FAQ - Client-side Identity Management
If you need more specific code examples or have a unique edge case, let me know!
kapa.ai is still learning and improving, please let me know how I did by reacting below.
ℹ️ Tip: Mention @kapa.ai in the thread for follow-ups or DM the app for 1-to-1 help.
Gabe
·
·
kapa.ai can you expan upon the difference of user properties and profiles? My understanding was that user properties were tied to the users profile, so whenever a user changes their in app profile, the users user properties would have to be set again and then their profile in mixpanel would reflect said change, is that correct?
kapa.ai
APP
·
·
Let me check the knowledge base for you again. One moment! 📚
kapa.ai
APP
·
·
You're correct that in Mixpanel, user properties are attributes that describe a user, and these are stored within the user's profile. In Mixpanel terminology:
- User Profile: This is the record or object in Mixpanel that represents a user. It is identified by a unique distinct_id and contains all the user properties for that user. - User Properties: These are the key-value pairs (like name, email, plan, etc.) that are stored on the user profile. They describe the current state or characteristics of the user.
When you update a user property (for example, if a user changes their in-app profile or switches between different profiles), you need to update the corresponding user properties in Mixpanel. The user profile in Mixpanel will then reflect the latest values you set. Mixpanel always joins events with the latest state of the user profile, not the state at the time the event occurred. This means if you change a user property, all future queries will use the new value, even for past events performed by that user.
If you want to track changes over time (for example, if a user switches between different in-app profiles), you should consider tracking the profile information as an event property on each event, rather than (or in addition to) as a user property. This way, you can analyze historical changes, since event properties are immutable and reflect the state at the time of the event, while user properties always show the latest state.
Here are some relevant points from the documentation:
- "User Profiles let you enrich events with demographic attributes (i.e. user properties) about the users that performed those events... A user profile has a set of user properties associated with a given user." User Profile: Demographic attributes for your users - "All Events join with the latest state of a User Profile, rather than its state at a point in time. If there are aspects of a user’s state that change over time (for example, their plan type), we recommend tracking that as a property on their events, so that you can analyze that change over time." User Profile FAQ
So, your understanding is correct: user properties are tied to the user profile, and updating them will update the profile in Mixpanel. But if you need to analyze historical changes, use event properties for those attributes that change frequently.
kapa.ai is still learning and improving, please let me know how I did by reacting below.
ℹ️ Tip: Mention @kapa.ai in the thread for follow-ups or DM the app for 1-to-1 help.
Gabe
·
·
kapa.ai Can you help me with figuring out how to identify previously signed up users that have had events recorded in mixpanel? Would we use identify() on sign up and log in, with the account id (setting it as the distinct id)? for setting their profile properties, would we set() the profile id and profiles demographic information on profile change? or can we have multiple profiles tied to one account id/distinct id?
kapa.ai
APP
·
·
Let me check the knowledge base for you again. One moment! 📚
kapa.ai
APP
·
·
To identify previously signed-up users who have had events recorded in Mixpanel (using the Original API), you should:
1. Call identify(account_id) on sign up and log in: Yes, you should use the identify() method with the account ID (which should be unique per user) both at sign up and log in. This will merge any anonymous events (recorded before sign up or log in) with the user's account, ensuring all activity is attributed to the correct user profile. This is the recommended approach for both registration and login flows Client-side Identity Management.
2. Setting profile properties: You can use .people.set() (or the equivalent in your SDK) to set user properties (such as profile ID and demographic information) after the user is identified. However, Mixpanel user profiles are tied to the distinct_id (in your case, the account ID). If a user can have multiple in-app profiles (e.g., solo, partner), you cannot have multiple Mixpanel user profiles for a single account ID. Instead, you should: - Store the active profile ID and its demographic information as user properties if you only care about the current state. - If you want to track changes over time or analyze activity by profile, include the profile ID and demographic information as event properties on each event. This way, you can segment events by profile, even though all events are tied to the same Mixpanel user profile User Profiles FAQ.
3. Multiple profiles per account: Mixpanel does not support multiple user profiles for a single distinct_id. All user properties are overwritten with the latest values set for that distinct_id. If you need to analyze activity by different in-app profiles under the same account, use event properties to capture the profile context for each event User Profiles FAQ.
Summary of best practices: - Use identify(account_id) at sign up and log in. - Set user properties (e.g., active profile ID, demographics) after identification, but remember these will always reflect the latest state. - For historical or per-profile analysis, include profile information as event properties.
If you need to support multiple profiles per account for analysis, event properties are the way to go, as Mixpanel user profiles are always 1:1 with distinct_id User Profiles FAQ.
kapa.ai is still learning and improving, please let me know how I did by reacting below.
ℹ️ Tip: Mention @kapa.ai in the thread for follow-ups or DM the app for 1-to-1 help.
Gabe
·
·
kapa.ai so if we want to have the demographics information for the current active profile that the account (user) is using, then would we call set() on profile switch, and update the information to reflect the currently active profile id's demographics info? and then set again on on profile switch back, so that the user properties are current to the browsing profile? and then we could also have all of those user properties as event properties to track events by user demographics historically?
kapa.ai
APP
·
·
Let me check the knowledge base for you again. One moment! 📚
kapa.ai
APP
·
·
Yes, your understanding is correct and aligns with Mixpanel’s best practices as described in the documentation:
- To keep the user profile’s demographic information current: When a user switches their active profile within your app, you should call .set() (or the equivalent in your SDK) to update the user properties on their Mixpanel profile to reflect the demographics of the currently active profile. This way, the user properties on the Mixpanel user profile (tied to the account’s distinct_id) will always represent the latest active profile’s information.
- On switching back to another profile: You would call .set() again to update the user properties to match the demographics of the newly active profile. This ensures that the user profile in Mixpanel always reflects the current state of the user’s active profile.
- For historical analysis: Since Mixpanel user properties always reflect the latest state (not the state at the time of the event), you should also include the relevant demographic information as event properties on each event. This allows you to analyze historical events by the profile demographics that were active when the event occurred, as event properties are immutable and tied to the event’s timestamp.
This approach is explicitly recommended in the documentation:
All Events join with the latest state of a User Profile, rather than its state at a point in time. If there are aspects of a user’s state that change over time (for example, their plan type), we recommend tracking that as a property on their events, so that you can analyze that change over time. User Profile FAQ
So, your plan to update user properties on profile switch and also include those properties as event properties for historical analysis is the correct and recommended approach.
kapa.ai is still learning and improving, please let me know how I did by reacting below.
ℹ️ Tip: Mention @kapa.ai in the thread for follow-ups or DM the app for 1-to-1 help.
Gabe
·
·
kapa.ai and what about reset()? should we call that on profile switch or only on account log out? Our users require phone number validation after a certain period of inactivity or after explicit sign out, and I see that it is recommended to call reset() on signup rather than log out so that we are not constantly resetting when users automatically sign out, is that something of concern to pay attention to?
kapa.ai
APP
·
·
Let me check the knowledge base for you again. One moment! 📚
kapa.ai
APP
·
·
You should not call reset() on profile switch within the same account. The purpose of reset() is to clear all identity information (including distinct_id and user properties) and generate a new anonymous ID, which is intended for when a completely new user/account is using the app on the same device—not when switching between profiles under the same account.
Best practices from the knowledge sources:
- Call .reset() only when there is an explicit intent to change to a new user/account (e.g., clicking "Sign-up" for a new account, or logging out of the app entirely). This prevents data from multiple users/accounts from being merged and avoids hitting the 500 ID cluster limit unnecessarily.
"A best practice would be to only call reset() if there is a definite intent to change user on the same device, example clicking on 'Sign-up' button instead of 'Login'." Identifying Users (Original) - Client-side Identity Management
- Do not call reset() on profile switch within the same account. Instead, just update the user properties to reflect the active profile, as discussed previously.
- Call reset() on account log out or when the app leaves an authenticated state (such as after phone number validation timeout or explicit sign out). This ensures that the next user on the device starts with a clean slate and prevents unintended merging of data between different accounts.
"By calling .reset() at logout or when a user enters an unauthenticated-state (such as timing out), you generate a new $device_id for your user, ensuring that multiple users that are sharing a single device would not be incorrect considered as a single user tracking events with the same IDs." Identifying Users (Simplified) - Best Practices
- On sign up: The documentation for the Original API recommends calling reset() only when there is a definite intent to change user, not on every log out or automatic sign out. This is to avoid unnecessary resets and potential issues with ID cluster limits.
Summary: - Call reset() on account log out or when a new account is being created on the same device. - Do not call reset() on profile switch within the same account. - Be mindful not to overuse reset() on automatic sign outs unless it truly represents a new user/account context.
This approach will keep your identity management clean and prevent data from being incorrectly merged or fragmented.
kapa.ai is still learning and improving, please let me know how I did by reacting below.
ℹ️ Tip: Mention @kapa.ai in the thread for follow-ups or DM the app for 1-to-1 help.
Gabe
·
·
kapa.ai With all of the context we've discussed, can you give me a step by step outline for the implementation

Best Practices for Implementing User Profiles in API Systems

29 comments

1. Setting the distinct_id

2. Managing Profile Identity

3. When to Identify and Reset

4. Setting User/Profile Properties

5. Example Flow

6. Additional Best Practices