1. Users
Returning.AI
  • Getting Started
  • Bulk Operations
    • List bulk update jobs
      GET
    • Get bulk update job status
      GET
    • Get bulk update job details
      GET
    • Bulk update users from CSV
      POST
    • Bulk update premium currency from CSV
      POST
  • Chart Analysis
    • Create Analysis
      POST
    • Get Analysis
      GET
    • Update Analysis
      PATCH
    • Delete Analysis
      DELETE
    • List Analyses
      GET
    • Append Drawings
      POST
  • Rewards & Redemptions
    • Update redemption order status
      PUT
    • List redemption orders by user email
      POST
    • List redemption statuses
      POST
    • Get redemption status by ID
      POST
    • List redemption orders by community
      POST
    • Create redemption order status
      POST
    • Get redemption order status history
      POST
  • Gamification
    • Leaderboards
      • List leaderboards with pagination
      • Create a new leaderboard
      • Update an existing leaderboard
      • Get a single leaderboard by ID
      • Delete a leaderboard
    • Streaks & Mini Games
      • List user streak logs
      • Update user spin-wheel information
    • Referral
      • Get referral programs
      • Get user's referral summary
    • Rolling Data
      • Get Daily Calculation Data
      • Get Rolling Calculation Data
    • Get tiers and XP settings
    • Get daily user gamification history
    • List user gamification logs
    • Get user activity stats
  • Messaging
    • Message Actions
      • Direct Channel
        • private DM channel
          • Reply Message
          • Send Message
          • React Message
        • public channel
          • Reply Message
          • Send Message
          • React Message
      • Forum Channel
        • Send Message
        • Reply Message
        • React Message
      • Text Channel
        • Reply Message
        • Send Message
        • React Message
      • Iframe Channel
        • Reply Message
        • Send Message
        • React Message
    • Get Messages
    • Send Message
    • Reply Message
    • React Message
    • Upload message images
  • Users
    • Get user
      GET
    • Get Users with Filters
      POST
    • Create New User
      POST
    • Get User Data
      POST
    • Manage User Account
      POST
    • List mini-game logs by user email
      POST
    • Get user's current Mini Games and Streak stats
      POST
    • Get User Milestones
      POST
    • Update User Data, Identifier, And Roles
      POST
  • Authentication
    • Register user with password
    • Verify user email
    • Log in user with password
    • Secure Auth
  • Channels
    • Iframe
    • List integration channels
  • Events
    • Outgoing webhooks
      • Encryption
      • User Joins Server
      • User Visits server
      • New Message Posted Anywhere
      • New Message Posted To channel
      • Purchased Store Item
    • Incoming webhooks
      • API Keys & Encryption
      • Send message into channels
      • Update Custom User Fields
      • Update In-game currency
  • Widgets
    • Authenticated Widgets
    • Public widgets
  • Store
    • Purchase History
      • Update purchase history redemption instructions or voucher details
    • Categories
      • List store categories
      • Create store category
      • Get store category by ID
      • Update store category
      • Delete store category
    • Products
      • List products
      • Create products in bulk
      • Create product with vouchers
      • Update products in bulk
      • Read product
      • Update product and append vouchers
      • Delete product
    • Redemption-transaction
      • Get Redemption Transaction Detail
    • Get store configuration
    • Update store configuration
  • Community Analytics
    • Get Loyalty Overview
    • Get Phone Verification Contacts
  • Community
    • Appearance
      • Update community theme colors
      • Update community bot profile
      • Update community URL metadata
      • Update community name and URL
    • Community Users
      • Get community users
      • Get user
    • Create community
  • API Keys
    • Community API Keys
      • Create API key
      • Read API keys
      • Delete API key
      • Update API key
    • User API Keys
      • List user API keys
      • Create user API key
      • Update user API key
      • Delete user API key
      • Get current API key information
  • User Fields
    • User Field History
      • List Community User-Field History
      • List One Field Across Users
      • List One User Across Fields
      • List One User's One Field
      • Update A User Field Value
      • Deprecated Field-First History Write
      • Deprecated Field-First History Read
    • Create A User Field Definition
    • Get Specific User Field
    • Update Custom User Field
    • Delete Custom User Field
    • Get all user fields for a community
    • Delete user field
    • Update user field
    • Get specific user field
  • Legacy
    • Servers
      • Create server
      • List servers
      • Update server metadata
    • Bulk Operations
      • Bulk import users from CSV
    • Badges
      • List badges
      • Create badge
      • Update badge
      • Delete badge
      • Remove badge from user
      • Award badge to user
    • Messaging
      • Reply to message
      • Send message
      • React to message
    • Roles & Permissions
      • List server roles
      • Create role
      • Update role
      • Delete role
      • List user roles
      • Add role to user
      • Remove role from user
    • Users
      • Upload user avatar
    • Channels
      • Create channel
      • Update channel
      • Delete channel
    • API Keys
      • List integration API keys
      • Create integration API key
      • Delete integration API key
      • Update integration API key
  1. Users

Create New User

POST
/v1/users
Create a user in the community resolved from the API key. Use this for broker onboarding, federated provisioning, or local-password accounts.

Important behavior#

Email and username duplicate locks are normalized and acquired separately in a fixed order, so concurrent collisions fail cleanly.
Boolean false, numerical 0, empty valid multi-line text, and ordinary strings are preserved in custom fields.
Passwords are accepted only for local-password users. They are never returned by this API and are redacted from API logs. If Returning.AI generates a password, deliver it through the configured account email flow.
Email, phone, custom-field values, and full success responses remain visible in authorized API logs for troubleshooting.

Recommended flow#

1.
Create the user with an Idempotency-Key.
2.
Save data.userId.
3.
Read the user with POST /v1/users/info.
4.
Treat a conflict as a lookup/reconciliation case, not as permission to create another identity.

Request

Authorization
Provide your bearer token in the
Authorization
header when making requests to protected resources.
Example:
Authorization: Bearer ********************
Header Params

Body Params application/jsonRequired

Examples

Responses

🟢200OK
application/json
User created successfully. Use data.userId for follow-up reads and communityMemberId as the created community membership record.
Bodyapplication/json

🟠400Bad Request
🟠401Unauthorized
🟠403Forbidden
🟠409
🔴500Server Error
Request Request Example
Shell
JavaScript
Java
Swift
cURL
curl --location 'https://sgtr-integration.returning.ai/apis/v1/users' \
--header 'Idempotency-Key;' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "firstname": "Ada",
    "lastname": "Lovelace",
    "username": "ada_lovelace_123",
    "displayname": "Ada Lovelace",
    "email": "ada@example.com",
    "accessLevel": 1,
    "joinServer": true,
    "sendEmail": false,
    "emailPassword": false,
    "externalId": "broker-user-123"
}'
Response Response Example
200 - Success Example
{
    "status": "success",
    "code": "USER_CREATED",
    "message": "User created successfully",
    "data": {
        "userId": "3247779",
        "username": "ada_lovelace_123",
        "email": "ada@example.com",
        "communityMemberId": "66f000000000000000000001",
        "identifierKey": "customerid",
        "externalId": "<brokerCustomerId-or-cognitoSub>",
        "created": true
    }
}
Modified at 2026-07-20 18:50:42
Previous
Get Users with Filters
Next
Get User Data
Built with