API Reference: Users

Overview

The Users API exposes team user accounts and the current user's own profile and device state. Use /v1/users/me to fetch the signed-in user, /v1/users to list team members, and /v1/users/{userSimplyId} to retrieve one member's profile. A set of current-user self-service endpoints under /v1/users/me/... covers preferences, mobile devices, sessions, recent visits, and MFA.

Key Concepts

• Team Admins — Users with full administrative access to configure collections, wizards, automations, and team settings.
• Team Users — Users with restricted access governed by feature permissions and data permissions.
• Current user — The signed-in user behind a Cognito JWT or Simply Login OAuth token. The /v1/users/me... endpoints require a user credential; they reject API keys.
• simplyId — Each user has a unique simplyId used in audit logs, automation execution logs, conversation participants, and more.

Endpoints

Method	Path	Purpose	Auth / Permission
GET	/v1/users/me	Current user, selected team, and permission flags.	Cognito JWT or Simply Login OAuth (not API keys)
PATCH	/v1/users/me	Update self-service preferences (e.g. defaultInterfaceLanguageId).	Cognito JWT only
GET	/v1/users	List team members.	TEAM_ADMIN_USERS
GET	/v1/users/{userSimplyId}	Get a team member by user simplyId.	TEAM_ADMIN_USERS
POST	/v1/users	Create a user with team associations.	System administrators only

Get Current User

Returns the signed-in user's profile, the selected team, and permission flags. Only available for user-authenticated requests (Cognito JWT or Simply Login OAuth); API-key callers receive 400 VALIDATION_ERROR. Optional expand query parameter accepts a comma-separated list of teams, rolePermissions, and permissionSnapshot. Each expanded team includes the membership's nullable lastOpened ISO date-time.

const me = await s360.users.me({ expand: ['teams'] });
console.log(`${me.data.firstName} ${me.data.lastName} <${me.data.email}>`);
console.log(`Team admin: ${me.data.permissions.isTeamAdmin}`);

curl -s "https://api.simply360.app/v1/users/me?expand=teams" \
  -H "Authorization: Bearer $S360_USER_ACCESS_TOKEN" \
  -H "X-Team-Id: $S360_TEAM_SIMPLY_ID"

List Team Users

Requires the TEAM_ADMIN_USERS feature permission. Each entry includes id, userSimplyId, email, firstName, lastName, isTeamAdmin, lastLoggedIn, and createdAt.

const users = await s360.users.list();
for (const user of users.data) {
  console.log(`${user.id}: ${user.firstName} ${user.lastName} (${user.email})`);
}

curl -s "https://api.simply360.app/v1/users" \
  -H "Authorization: Bearer $S360_API_KEY"

Get a Specific User

Requires TEAM_ADMIN_USERS. Returns 404 when the user does not belong to the selected team.

const user = await s360.users.get('USER-1234-ABCD');

curl -s "https://api.simply360.app/v1/users/USER-1234-ABCD" \
  -H "Authorization: Bearer $S360_API_KEY"

Current-User Self-Service Endpoints

These endpoints operate on the signed-in user and require a user credential (Cognito JWT, or an allowlisted first-party OAuth client for the mobile apps). They are not available to API keys.

Method	Path	Purpose
GET	/v1/users/me/mobile-devices	List the current user's registered mobile devices.
POST	/v1/users/me/mobile-devices/current	Register or refresh the current mobile app installation (installationId + platform).
PUT	/v1/users/me/mobile-devices/{deviceSimplyId}	Update a device profile.
PUT	/v1/users/me/mobile-devices/current/settings	Back up the current device's app settings.
GET	/v1/users/me/mobile-devices/{deviceSimplyId}/settings	Fetch a device's settings backup.
GET / POST / DELETE	/v1/users/me/recent-visits	List, record, and clear the user's recent visits.
GET / POST	/v1/users/me/sessions	List sessions / create a session record for the current user.
DELETE	/v1/users/me/sessions/{sessionSimplyId}	Revoke one of the current user's sessions.

MFA Endpoints

TOTP multi-factor authentication for the current user is managed under /v1/users/me/mfa (Cognito JWT only): GET .../status, POST .../setup, POST .../verify, POST .../complete-setup, and DELETE /v1/users/me/mfa to disable. Team-level MFA administration lives at GET /v1/users/mfa/compliance and POST /v1/users/mfa/reset/{teamUserLinkSimplyId}.

Usage Notes

• /v1/users/me requires a user token (Cognito JWT or Simply Login OAuth with identity:read). API keys are rejected with 400 because a key does not carry a user identity. Use the dashboard-issued bearer token plus the X-Team-Id header to select a team.
• User simplyId values appear throughout the platform — in audit logs, automation execution logs, conversation participants, message senders, and more.
• Inviting, deactivating, and role-managing team members is handled by the team-user administration surface (invitations, links, roles, and data permissions) or in the Simply360 dashboard. POST /v1/users itself is restricted to system administrators.
• Deactivated users cannot log in but their profiles are retained for audit-trail purposes.