> ## Documentation Index > Fetch the complete documentation index at: https://docs.mlm-platform.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a new member > Creates a new member in the MLM hierarchy. The member can optionally be placed under a parent (sponsor) using `parent_id` or `referral_code`. **Guardrails:** - If `can_recruit` is false for the parent, the request will fail with 403 - Email must be unique within the tenant ## OpenAPI ````yaml api/openapi.yaml post /api/v1/users openapi: 3.1.0 info: title: MLM Platform API version: 1.0.0 description: > The MLM Platform API enables tenant developers to integrate commission tracking, member management, and referral systems into their applications. ## Authentication All API requests require a tenant API key passed in the `x-tenant-api-key` header. ## Environments - **LIVE**: Production environment with real data - **SANDBOX**: Test environment for development and testing API keys are scoped to specific environments. Use sandbox keys for testing. The environment is derived from the API key used for the request. The platform returns the selected environment in the response header `X-Environment`. If you send an `X-Environment` request header, it is treated as optional/debug-only. contact: name: MLM Platform Support email: support@mlm-platform.example.com license: name: Proprietary url: https://mlm-platform.example.com/terms servers: - url: https://app.mlm-platform.com description: Production API - url: http://localhost:3000 description: Local Development security: - TenantApiKey: [] tags: - name: Auth description: Token exchange, validation, refresh, and revocation for OIDC federation - name: Events description: Purchase and commission events - name: Users description: Member management - name: Leads description: Lead capture and tracking - name: Referrals description: Referral links and codes - name: Payout description: Payout methods metadata for dynamic payout setup forms - name: Payout Accounts description: Member payout accounts (create/list/update/delete) - name: KYC description: Member KYC start, status, and document submission - name: Admin KYC description: Admin KYC review queue, details, and actions - name: Widget description: Embeddable widget authentication - name: Webhooks description: Webhook receivers for third-party providers (Sumsub) paths: /api/v1/users: post: tags: - Users summary: Create a new member description: > Creates a new member in the MLM hierarchy. The member can optionally be placed under a parent (sponsor) using `parent_id` or `referral_code`. **Guardrails:** - If `can_recruit` is false for the parent, the request will fail with 403 - Email must be unique within the tenant operationId: createUser requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateUserRequest' examples: basic: summary: Basic member creation value: email: newmember@example.com membership_tier: ORDINARY withParent: summary: Member with sponsor value: email: newmember@example.com membership_tier: ORDINARY parent_id: 550e8400-e29b-41d4-a716-446655440000 withReferralCode: summary: Member via referral code value: email: newmember@example.com membership_tier: ORDINARY referral_code: ABC123 responses: '201': description: Member created successfully content: application/json: schema: $ref: '#/components/schemas/User' headers: X-Environment: $ref: '#/components/headers/X-Environment' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': description: Forbidden - Parent cannot recruit content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Parent user cannot recruit new members code: CANNOT_RECRUIT '409': description: Conflict - Email already exists content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: A user with this email already exists code: EMAIL_EXISTS '500': $ref: '#/components/responses/InternalError' components: schemas: CreateUserRequest: type: object required: - email properties: email: type: string format: email description: User's email address (must be unique) membership_tier: $ref: '#/components/schemas/MembershipTier' parent_id: type: string format: uuid description: Parent/sponsor user ID referral_code: type: string description: Referral code to attribute to a sponsor is_active: type: boolean default: true description: Whether the user is active can_recruit: type: boolean default: true description: Whether the user can recruit new members metadata: type: object additionalProperties: true User: type: object properties: id: type: string format: uuid tenant_id: type: string format: uuid email: type: string format: email membership_tier: $ref: '#/components/schemas/MembershipTier' parent_id: type: string format: uuid nullable: true is_active: type: boolean can_recruit: type: boolean is_test_user: type: boolean created_at: type: string format: date-time updated_at: type: string format: date-time ErrorResponse: type: object required: - error properties: error: type: string description: Human-readable error message code: type: string description: Machine-readable error code details: type: object additionalProperties: true description: Additional error details MembershipTier: type: string enum: - ORDINARY - SENIOR - MANAGER - DIRECTOR description: Member's tier in the hierarchy headers: X-Environment: description: >- Indicates the environment (LIVE or SANDBOX) the request was processed in (derived from API key) schema: type: string enum: - LIVE - SANDBOX responses: BadRequest: description: Bad Request - Invalid input content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Invalid request body code: VALIDATION_ERROR details: field: email message: Invalid email format Unauthorized: description: Unauthorized - Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missing_api_key: summary: Missing API key value: error: Authentication required code: UNAUTHORIZED invalid_api_key: summary: Invalid API key value: error: Invalid API key code: INVALID_API_KEY InternalError: description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: An unexpected error occurred code: INTERNAL_ERROR securitySchemes: TenantApiKey: type: apiKey in: header name: x-tenant-api-key description: > Tenant API key for authentication. Keys are scoped to specific environments (LIVE or SANDBOX). Obtain keys from the admin dashboard. ````