Users API

Users API

The Users API provides comprehensive user profile management, including personal information, preferences, addresses, loyalty program data, and privacy controls for the OSUS.AI platform.

Base URL: https://api.osus.ai/v1/users
Authentication Required: All endpoints require a valid JWT token.

User Data Categories

Profile Data

Personal information, contact details, and account settings

Address Book

Shipping and billing addresses with delivery preferences

Loyalty Program

Points, tier status, rewards, and referral information

Preferences

Language, currency, notifications, and privacy settings

Get User Profile

Retrieve the authenticated user's complete profile information.

GET /users/profile

Example Request

curl -X GET https://api.osus.ai/v1/users/profile \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "data": {
    "user": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "ahmed@example.com",
      "phone": "+201234567890",
      "firstName": "Ahmed",
      "lastName": "Mohamed",
      "dateOfBirth": "1990-05-15",
      "gender": "male",
      "avatar": "https://cdn.osus.ai/avatars/user-001.jpg",
      "accountType": "individual",
      "accountStatus": "active",
      "emailVerified": true,
      "phoneVerified": true,
      "businessInfo": null,
      "preferences": {
        "language": "ar",
        "currency": "EGP",
        "timezone": "Africa/Cairo",
        "notifications": {
          "email": {
            "marketing": true,
            "orders": true,
            "security": true
          },
          "sms": {
            "orders": true,
            "delivery": true,
            "security": false
          },
          "push": {
            "orders": true,
            "recommendations": true,
            "reminders": false
          }
        },
        "privacy": {
          "profileVisibility": "private",
          "showInSearch": false,
          "dataProcessing": true
        }
      },
      "loyaltyInfo": {
        "tier": "gold",
        "points": 2450,
        "totalSpent": 15780,
        "nextTierProgress": 75,
        "nextTierThreshold": 20000,
        "referralCode": "AHMED2025",
        "referralsCount": 3
      },
      "addresses": [
        {
          "id": "addr-001",
          "label": "Home",
          "firstName": "Ahmed",
          "lastName": "Mohamed",
          "addressLine1": "123 Tahrir Square",
          "addressLine2": "Apt 4B",
          "city": "Cairo",
          "governorate": "Cairo",
          "postalCode": "11511",
          "country": "EG",
          "phone": "+201234567890",
          "isDefault": true,
          "isBillingAddress": true,
          "addressType": "residential"
        }
      ],
      "statistics": {
        "totalOrders": 12,
        "totalSpent": 15780,
        "averageOrderValue": 1315,
        "favoriteCategory": "furniture",
        "memberSince": "2023-03-15T10:00:00Z",
        "lastLogin": "2025-01-15T09:30:00Z"
      },
      "createdAt": "2023-03-15T10:00:00Z",
      "updatedAt": "2025-01-15T08:45:00Z"
    }
  },
  "timestamp": "2025-01-15T10:30:00Z",
  "requestId": "req_123456"
}

Update User Profile

Update user profile information and preferences.

PUT /users/profile

Request Body

Parameter Type Description
firstName string User's first name
lastName string User's last name
phone string Phone number (Egyptian format)
dateOfBirth string Date of birth (YYYY-MM-DD)
gender string Gender: male, female, other
avatar file Profile picture (multipart/form-data)

Example Request

curl -X PUT https://api.osus.ai/v1/users/profile \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Ahmed",
    "lastName": "Mohamed",
    "phone": "+201234567890",
    "dateOfBirth": "1990-05-15",
    "gender": "male"
  }'

Address Management

Manage user's shipping and billing addresses.

GET /users/addresses

Get all user addresses

POST /users/addresses

Add new address

GET /users/addresses/{addressId}

Get specific address

PUT /users/addresses/{addressId}

Update address

DELETE /users/addresses/{addressId}

Delete address

Add Address Request

curl -X POST https://api.osus.ai/v1/users/addresses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Office",
    "firstName": "Ahmed",
    "lastName": "Mohamed",
    "companyName": "OSUS Technology",
    "addressLine1": "456 Nile Corniche",
    "addressLine2": "Floor 10",
    "city": "Cairo",
    "governorate": "Cairo",
    "postalCode": "11511",
    "country": "EG",
    "phone": "+201234567890",
    "deliveryInstructions": "Call before delivery",
    "isDefault": false,
    "isBillingAddress": false,
    "addressType": "commercial"
  }'

User Preferences

Manage user preferences including language, notifications, and privacy settings.

PUT /users/preferences

Preferences Structure

Category Setting Options Default
General language ar, en, fr ar
currency EGP, USD, EUR EGP
timezone Africa/Cairo, etc. Africa/Cairo
Email Notifications marketing true, false true
orders true, false true
security true, false true
Privacy profileVisibility public, private private
dataProcessing true, false true

Example Request

curl -X PUT https://api.osus.ai/v1/users/preferences \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "language": "en",
    "currency": "EGP",
    "notifications": {
      "email": {
        "marketing": false,
        "orders": true,
        "security": true
      },
      "sms": {
        "orders": true,
        "delivery": true
      },
      "push": {
        "orders": true,
        "recommendations": false
      }
    },
    "privacy": {
      "profileVisibility": "private",
      "showInSearch": false,
      "dataProcessing": true
    }
  }'

Loyalty Program

Access loyalty program information, points, and tier benefits.

GET /users/loyalty

Loyalty Tiers

Bronze

EGP 0 - 4,999

Silver

EGP 5,000 - 14,999

Gold

EGP 15,000 - 39,999

Platinum

EGP 40,000+

Loyalty Response

{
  "success": true,
  "data": {
    "loyalty": {
      "currentTier": "gold",
      "points": 2450,
      "totalSpent": 15780,
      "nextTier": "platinum",
      "nextTierThreshold": 40000,
      "nextTierProgress": 39.45,
      "pointsToNextTier": 24220,
      "referralCode": "AHMED2025",
      "referralsCount": 3,
      "referralEarnings": 450,
      "benefits": {
        "discountPercentage": 5,
        "freeShipping": true,
        "prioritySupport": true,
        "earlyAccess": true,
        "specialEvents": true
      },
      "pointsHistory": [
        {
          "id": "pts-001",
          "type": "earned",
          "points": 150,
          "description": "Order #OSUS-2025-000012",
          "orderId": "ord-123456",
          "createdAt": "2025-01-10T14:30:00Z"
        },
        {
          "id": "pts-002",
          "type": "redeemed",
          "points": -500,
          "description": "10% discount on order",
          "orderId": "ord-123455",
          "createdAt": "2025-01-08T11:15:00Z"
        }
      ]
    }
  }
}

Wishlist Management

Manage user's saved products and wish lists.

GET /users/wishlist

Get user's wishlist

POST /users/wishlist/items

Add item to wishlist

DELETE /users/wishlist/items/{productId}

Remove item from wishlist

Wishlist Response

{
  "success": true,
  "data": {
    "wishlist": {
      "id": "wish-001",
      "userId": "550e8400-e29b-41d4-a716-446655440000",
      "items": [
        {
          "id": "wish-item-001",
          "productId": "550e8400-e29b-41d4-a716-446655440000",
          "product": {
            "name": "Modern 3-Seat Sofa",
            "price": 2500,
            "image": "https://cdn.osus.ai/products/sofa-001-main.jpg",
            "inStock": true,
            "hasDiscount": true,
            "discountPercentage": 20
          },
          "variantId": "var-001",
          "addedAt": "2025-01-10T15:30:00Z",
          "priceWhenAdded": 2500,
          "priceChangeAlert": false
        }
      ],
      "totalItems": 1,
      "totalValue": 2500,
      "lastUpdated": "2025-01-10T15:30:00Z"
    }
  }
}

Account Settings

Manage account security, password, and data export/deletion.

PUT /users/password

Change password

POST /users/verify-email

Request email verification

POST /users/verify-phone

Request phone verification

GET /users/data-export

Export user data (GDPR)

DELETE /users/account

Delete account

Change Password Request

curl -X PUT https://api.osus.ai/v1/users/password \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "currentPassword": "currentPassword123",
    "newPassword": "newSecurePassword456!",
    "confirmPassword": "newSecurePassword456!"
  }'

Error Codes

HTTP Status Error Code Description
400 INVALID_PROFILE_DATA Invalid profile data provided
400 INVALID_ADDRESS_DATA Invalid address data provided
400 WEAK_PASSWORD New password doesn't meet requirements
400 INCORRECT_PASSWORD Current password is incorrect
404 ADDRESS_NOT_FOUND Address with specified ID not found
409 EMAIL_ALREADY_EXISTS Email address already in use
409 PHONE_ALREADY_EXISTS Phone number already in use
422 INVALID_VERIFICATION_CODE Invalid or expired verification code