Users API

Overview

The Users API manages user profiles, account settings, and user data.

Endpoints

Method	Endpoint	Description	Permission
GET	`/api/users`	List users	`users:read`
GET	`/api/users/:id`	Get user profile	`profile:read`
PATCH	`/api/users/:id`	Update user profile	`profile:write`
DELETE	`/api/users/:id`	Delete user account	`users:delete`

List Users

Get paginated list of users (admin only).

Request

GET /api/users?page=1&limit=10&role=talent
Authorization: Bearer <admin_token>

Query Parameters

Parameter	Type	Default	Description
`page`	number	1	Page number
`limit`	number	10	Items per page
`role`	string	-	Filter by role
`search`	string	-	Search by name/email

Response

{
  "data": [
    {
      "id": "user_123",
      "email": "john@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "role": "talent",
      "avatar": "https://example.com/avatar.jpg",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 500,
    "totalPages": 50
  }
}

Get User Profile

Get detailed user profile information.

Request

GET /api/users/user_123
Authorization: Bearer <token>

Response

{
  "id": "user_123",
  "email": "john@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "role": "talent",
  "avatar": "https://example.com/avatar.jpg",
  "phone": "+63 912 345 6789",
  "location": "Manila, Philippines",
  "bio": "Experienced software engineer with...",
  "skills": ["React", "TypeScript", "Node.js"],
  "experience": [
    {
      "id": "exp_1",
      "company": "Tech Corp",
      "title": "Senior Developer",
      "startDate": "2022-01-01",
      "endDate": null,
      "current": true,
      "description": "Leading frontend development..."
    }
  ],
  "education": [
    {
      "id": "edu_1",
      "institution": "University of the Philippines",
      "degree": "Bachelor of Science",
      "field": "Computer Science",
      "startDate": "2014-06-01",
      "endDate": "2018-05-01"
    }
  ],
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Update User Profile

Update user profile information.

Request

PATCH /api/users/user_123
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "firstName": "John",
  "lastName": "Doe",
  "phone": "+63 912 345 6789",
  "location": "Cebu, Philippines",
  "bio": "Updated bio...",
  "skills": ["React", "TypeScript", "Node.js", "Python"]
}

Updatable Fields

Field	Type	Description
`firstName`	string	First name
`lastName`	string	Last name
`phone`	string	Phone number
`location`	string	Location
`bio`	string	Biography
`skills`	string[]	Skills list
`avatar`	string	Avatar URL

Response

{
  "id": "user_123",
  "firstName": "John",
  "lastName": "Doe",
  "phone": "+63 912 345 6789",
  "location": "Cebu, Philippines",
  "bio": "Updated bio...",
  "skills": ["React", "TypeScript", "Node.js", "Python"],
  "updatedAt": "2024-01-16T09:00:00Z"
}

Delete User Account

Delete a user account (admin or self).

Request

DELETE /api/users/user_123
Authorization: Bearer <token>

Response

{
  "message": "User account deleted successfully"
}

Add Work Experience

Add work experience to profile.

Request

POST /api/users/user_123/experience
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "company": "New Company",
  "title": "Software Engineer",
  "startDate": "2024-01-01",
  "current": true,
  "description": "Working on..."
}

Response

{
  "id": "exp_2",
  "company": "New Company",
  "title": "Software Engineer",
  "startDate": "2024-01-01",
  "endDate": null,
  "current": true,
  "description": "Working on..."
}

Add Education

Add education to profile.

Request

POST /api/users/user_123/education
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "institution": "MIT",
  "degree": "Master of Science",
  "field": "Computer Science",
  "startDate": "2020-09-01",
  "endDate": "2022-05-01"
}

Response

{
  "id": "edu_2",
  "institution": "MIT",
  "degree": "Master of Science",
  "field": "Computer Science",
  "startDate": "2020-09-01",
  "endDate": "2022-05-01"
}

Types

type UserRole = "employer" | "talent";
 
interface User {
  id: string;
  email: string;
  firstName: string;
  lastName: string;
  role: UserRole;
  avatar?: string;
  createdAt: string;
  updatedAt: string;
}
 
interface UserProfile extends User {
  phone?: string;
  location?: string;
  bio?: string;
  skills?: string[];
  experience?: WorkExperience[];
  education?: Education[];
}
 
interface WorkExperience {
  id: string;
  company: string;
  title: string;
  startDate: string;
  endDate?: string;
  current: boolean;
  description?: string;
}
 
interface Education {
  id: string;
  institution: string;
  degree: string;
  field: string;
  startDate: string;
  endDate?: string;
}

Domain Types

The shared package also defines domain types with utility functions:

// @hireable/shared/types/domain/user
type Role = "ADMIN" | "EMPLOYER" | "TALENT" | "GUEST";
 
interface User {
  id: string;
  email: string;
  firstName: string;
  lastName: string;
  role: Role;
  avatar?: string;
  createdAt: Date;
  updatedAt: Date;
}
 
// Utility functions
function getFullName(user: Pick<User, "firstName" | "lastName">): string;
function getInitials(user: Pick<User, "firstName" | "lastName">): string;

Frontend Integration

import { usersService } from "@/features/users";
 
// Get current user profile
const profile = await usersService.getProfile();
 
// Update profile
await usersService.updateProfile({
  bio: "Updated bio...",
  skills: ["React", "TypeScript"],
});
 
// Add experience
await usersService.addExperience({
  company: "Tech Corp",
  title: "Developer",
  startDate: "2024-01-01",
  current: true,
});

Permission Matrix

Action	ADMIN	EMPLOYER	TALENT
List users	✓	-	-
View any profile	✓	-	-
View own profile	✓	✓	✓
Update own profile	✓	✓	✓
Delete any user	✓	-	-
Delete own account	✓	✓	✓

On this page