Documentation

User Management API

SmartCV user management API documentation, including user information, account settings, subscription management and other features

Updated: 12/30/2024

SmartCV user management API provides user information management, account settings, subscription management, and other features.

📋 API Endpoint Overview

Endpoint	Method	Description
`/api/account`	GET	Get user information
`/api/account`	PUT	Update user information
`/api/account/security`	PUT	Update security settings
`/api/account/subscription`	GET	Get subscription information
`/api/account/subscription`	POST	Create subscription
`/api/account/subscription`	PUT	Update subscription

👤 Get User Information

Endpoint: GET /api/account

Description: Get detailed information of the current user

Authentication: Required login

Response:

{
  "success": true,
  "data": {
    "id": "user_123",
    "email": "user@example.com",
    "name": "Zhang San",
    "avatar": "https://storage.smartcv.cc/avatars/user_123.jpg",
    "emailVerified": true,
    "emailVerifiedAt": "2024-01-15T10:00:00Z",
    "subscriptionType": "PREMIUM",
    "subscriptionStatus": "ACTIVE",
    "subscriptionExpiresAt": "2025-01-15T10:00:00Z",
    "resumesCreated": 8,
    "resumesLimit": 50,
    "apiRequestsUsed": 150,
    "apiRequestsLimit": 1000,
    "storageUsed": 10485760,
    "storageLimit": 104857600,
    "preferences": {
      "language": "zh-cn",
      "timezone": "Asia/Shanghai",
      "theme": "light",
      "emailNotifications": true,
      "marketingEmails": false
    },
    "createdAt": "2024-01-15T10:00:00Z",
    "updatedAt": "2024-12-30T10:00:00Z",
    "lastLoginAt": "2024-12-30T09:00:00Z"
  }
}

✏️ Update User Information

Endpoint: PUT /api/account

Description: Update user's basic information and preferences

Authentication: Required login

Request Body:

{
  "name": "Li Si",
  "avatar": "https://storage.smartcv.cc/avatars/new_avatar.jpg",
  "preferences": {
    "language": "en",
    "timezone": "America/New_York",
    "theme": "dark",
    "emailNotifications": false,
    "marketingEmails": true
  }
}

Response:

{
  "success": true,
  "data": {
    /* Updated user information */
  }
}

🔒 Update Security Settings

Endpoint: PUT /api/account/security

Description: Update user's password and security settings

Authentication: Required login

Request Body:

{
  "currentPassword": "currentPassword123",
  "newPassword": "newSecurePassword456",
  "confirmPassword": "newSecurePassword456",
  "twoFactorEnabled": true
}

Response:

{
  "success": true,
  "message": "Security settings updated successfully",
  "data": {
    "passwordUpdated": true,
    "twoFactorEnabled": true,
    "backupCodes": ["12345678", "87654321", "11223344"]
  }
}

📊 Get Subscription Information

Endpoint: GET /api/account/subscription

Description: Get user's subscription details and usage

Authentication: Required login

Response:

{
  "success": true,
  "data": {
    "id": "sub_123",
    "type": "PREMIUM",
    "status": "ACTIVE",
    "currentPeriodStart": "2024-12-01T00:00:00Z",
    "currentPeriodEnd": "2025-01-01T00:00:00Z",
    "cancelAtPeriodEnd": false,
    "trialEnd": null,
    "plan": {
      "id": "plan_premium_monthly",
      "name": "Premium Monthly Plan",
      "price": 29.99,
      "currency": "USD",
      "interval": "month",
      "features": ["Unlimited resumes", "All premium templates", "AI optimization features", "Priority customer support", "1000 API requests/month"]
    },
    "usage": {
      "resumesCreated": 8,
      "resumesLimit": -1,
      "apiRequestsUsed": 150,
      "apiRequestsLimit": 1000,
      "storageUsed": 10485760,
      "storageLimit": 104857600,
      "resetDate": "2025-01-01T00:00:00Z"
    },
    "paymentMethod": {
      "type": "card",
      "last4": "4242",
      "brand": "visa",
      "expiryMonth": 12,
      "expiryYear": 2025
    },
    "nextBilling": {
      "date": "2025-01-01T00:00:00Z",
      "amount": 29.99,
      "currency": "USD"
    }
  }
}

💳 Create Subscription

Endpoint: POST /api/account/subscription

Description: Create new subscription plan

Authentication: Required login

Request Body:

{
  "planId": "plan_premium_monthly",
  "paymentMethodId": "pm_1234567890",
  "couponCode": "WELCOME20"
}

Response:

{
  "success": true,
  "data": {
    "subscriptionId": "sub_123",
    "status": "ACTIVE",
    "clientSecret": "pi_1234567890_secret_xyz",
    "requiresAction": false,
    "nextAction": null
  }
}

🔄 Update Subscription

Endpoint: PUT /api/account/subscription

Description: Update existing subscription (upgrade, downgrade, cancel, etc.)

Authentication: Required login

Request Body:

{
  "action": "upgrade",
  "planId": "plan_premium_yearly",
  "prorationBehavior": "create_prorations"
}

Supported Actions:

upgrade: Upgrade plan
downgrade: Downgrade plan
cancel: Cancel subscription
reactivate: Reactivate subscription
update_payment_method: Update payment method

Response:

{
  "success": true,
  "data": {
    "subscriptionId": "sub_123",
    "status": "ACTIVE",
    "prorationAmount": 15.5,
    "effectiveDate": "2024-12-30T10:00:00Z"
  }
}

📝 Usage Examples

JavaScript Example

// Get user information
async function getUserInfo() {
  const response = await fetch('/api/account', {
    credentials: 'include'
  })
 
  const data = await response.json()
  if (data.success) {
    return data.data
  } else {
    throw new Error(data.error)
  }
}
 
// Update user preferences
async function updateUserPreferences(preferences) {
  const response = await fetch('/api/account', {
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json'
    },
    credentials: 'include',
    body: JSON.stringify({
      preferences
    })
  })
 
  return response.json()
}
 
// Change password
async function changePassword(currentPassword, newPassword) {
  const response = await fetch('/api/account/security', {
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json'
    },
    credentials: 'include',
    body: JSON.stringify({
      currentPassword,
      newPassword,
      confirmPassword: newPassword
    })
  })
 
  const data = await response.json()
  if (data.success) {
    return data.data
  } else {
    throw new Error(data.error)
  }
}
 
// Get subscription information
async function getSubscriptionInfo() {
  const response = await fetch('/api/account/subscription', {
    credentials: 'include'
  })
 
  return response.json()
}
 
// Upgrade subscription
async function upgradeSubscription(planId) {
  const response = await fetch('/api/account/subscription', {
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json'
    },
    credentials: 'include',
    body: JSON.stringify({
      action: 'upgrade',
      planId
    })
  })
 
  return response.json()
}

React Hook Example

import { useState, useEffect } from 'react'
 
function useUserAccount() {
  const [user, setUser] = useState(null)
  const [subscription, setSubscription] = useState(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState(null)
 
  useEffect(() => {
    fetchUserData()
  }, [])
 
  const fetchUserData = async () => {
    try {
      setLoading(true)
 
      const [userResponse, subscriptionResponse] = await Promise.all([
        fetch('/api/account', { credentials: 'include' }),
        fetch('/api/account/subscription', { credentials: 'include' })
      ])
 
      const userData = await userResponse.json()
      const subscriptionData = await subscriptionResponse.json()
 
      if (userData.success) {
        setUser(userData.data)
      }
 
      if (subscriptionData.success) {
        setSubscription(subscriptionData.data)
      }
    } catch (err) {
      setError('Failed to fetch user information')
    } finally {
      setLoading(false)
    }
  }
 
  const updatePreferences = async (preferences) => {
    try {
      const response = await fetch('/api/account', {
        method: 'PUT',
        headers: {
          'Content-Type': 'application/json'
        },
        credentials: 'include',
        body: JSON.stringify({ preferences })
      })
 
      const data = await response.json()
      if (data.success) {
        setUser(data.data)
        return data.data
      } else {
        throw new Error(data.error)
      }
    } catch (err) {
      setError(err.message)
      throw err
    }
  }
 
  const changePassword = async (currentPassword, newPassword) => {
    try {
      const response = await fetch('/api/account/security', {
        method: 'PUT',
        headers: {
          'Content-Type': 'application/json'
        },
        credentials: 'include',
        body: JSON.stringify({
          currentPassword,
          newPassword,
          confirmPassword: newPassword
        })
      })
 
      const data = await response.json()
      if (data.success) {
        return data.data
      } else {
        throw new Error(data.error)
      }
    } catch (err) {
      setError(err.message)
      throw err
    }
  }
 
  return {
    user,
    subscription,
    loading,
    error,
    updatePreferences,
    changePassword,
    refetch: fetchUserData
  }
}
 
// User settings component example
function UserSettings() {
  const { user, updatePreferences } = useUserAccount()
  const [preferences, setPreferences] = useState(user?.preferences || {})
 
  const handleSave = async () => {
    try {
      await updatePreferences(preferences)
      alert('Settings saved successfully')
    } catch (error) {
      alert('Save failed: ' + error.message)
    }
  }
 
  if (!user) return <div>Loading...</div>
 
  return (
    <div className="user-settings">
      <h2>User Settings</h2>
 
      <div className="setting-group">
        <label>Language Settings</label>
        <select
          value={preferences.language}
          onChange={(e) =>
            setPreferences({
              ...preferences,
              language: e.target.value
            })
          }
        >
          <option value="zh-cn">中文</option>
          <option value="en">English</option>
        </select>
      </div>
 
      <div className="setting-group">
        <label>Theme Settings</label>
        <select
          value={preferences.theme}
          onChange={(e) =>
            setPreferences({
              ...preferences,
              theme: e.target.value
            })
          }
        >
          <option value="light">Light</option>
          <option value="dark">Dark</option>
          <option value="auto">Auto</option>
        </select>
      </div>
 
      <div className="setting-group">
        <label>
          <input
            type="checkbox"
            checked={preferences.emailNotifications}
            onChange={(e) =>
              setPreferences({
                ...preferences,
                emailNotifications: e.target.checked
              })
            }
          />
          Receive email notifications
        </label>
      </div>
 
      <button onClick={handleSave}>Save Settings</button>
    </div>
  )
}

❌ Error Handling

Common Error Codes

Error Code	HTTP Status	Description
`USER_NOT_FOUND`	404	User does not exist
`INVALID_PASSWORD`	400	Current password is incorrect
`WEAK_PASSWORD`	422	New password is too weak
`SUBSCRIPTION_NOT_FOUND`	404	Subscription does not exist
`PAYMENT_FAILED`	402	Payment failed
`PLAN_NOT_FOUND`	404	Subscription plan does not exist
`SUBSCRIPTION_LIMIT_EXCEEDED`	429	Subscription limit exceeded

Error Response Example

{
  "error": "Current password is incorrect",
  "code": "INVALID_PASSWORD",
  "details": {
    "field": "currentPassword"
  }
}

📊 Subscription Plan Description

Available Plan Types

Plan Type	Price	Features
`FREE`	Free	5 resumes, basic templates
`PREMIUM`	$29.99/month	Unlimited resumes, all templates, AI features
`ENTERPRISE`	Contact Sales	Team collaboration, API access, custom branding

Usage Limits

Usage limits for different subscription types:

{
  "FREE": {
    "resumesLimit": 5,
    "templatesAccess": "basic",
    "aiFeatures": false,
    "apiRequestsLimit": 100,
    "storageLimit": 10485760
  },
  "PREMIUM": {
    "resumesLimit": -1,
    "templatesAccess": "all",
    "aiFeatures": true,
    "apiRequestsLimit": 1000,
    "storageLimit": 104857600
  },
  "ENTERPRISE": {
    "resumesLimit": -1,
    "templatesAccess": "all",
    "aiFeatures": true,
    "apiRequestsLimit": -1,
    "storageLimit": -1
  }
}

Next Steps

🤖 AI Services

Learn how to use AI analysis and optimization features

View AI API →

🔗 Webhooks

Learn how to use Webhooks to receive real-time notifications

View Webhooks →

Need help?Contact us for support

Getting Started User Guide Support

Last updated: 12/30/2024 •Suggest improvements