Search for users by username, email, or display name with context-aware responses. Supports both public @mentions and admin-only full data searches.

Endpoints

Search Users

Endpoint: GET /wp-json/extrachill/v1/users/search

Purpose: Find users by search term for mentions, autocomplete, or admin relationship management.

Permission:

• mentions context: Requires logged-in user
• admin context: Requires manage_options capability
• artist-capable context: Requires logged-in user who can create artist profiles

Parameters:

• term (string, required) – Search query term (minimum 1 character for mentions, 2 for admin/artist-capable)
• context (string, optional) – Search context: mentions (default), admin, or artist-capable
• exclude_artist_id (int, optional) – Exclude existing roster members (artist-capable context only)

Request Examples:

Mentions context (public @mention autocomplete):

GET /wp-json/extrachill/v1/users/search?term=chris&context=mentions

Admin context (user relationship management):

GET /wp-json/extrachill/v1/users/[email protected]&context=admin

Response – Mentions Context (HTTP 200):

[
  {
    "id": 1,
    "username": "chris",
    "slug": "chris",
    "avatar_url": "https://example.com/avatar.jpg",
    "profile_url": "https://community.extrachill.com/users/chris"
  }
]

Response – Admin Context (HTTP 200):

[
  {
    "id": 1,
    "display_name": "Chris Huber",
    "username": "chris",
    "email": "[email protected]",
    "avatar_url": "https://example.com/wp-content/uploads/avatar.jpg"
  },
  {
    "id": 5,
    "display_name": "Christina Brown",
    "username": "christine",
    "email": "[email protected]",
    "avatar_url": "https://example.com/wp-content/uploads/avatar2.jpg"
  }
]

Response – Artist-Capable Context (HTTP 200):

[
  {
    "id": 1,
    "display_name": "Chris Huber",
    "username": "chris",
    "email": "[email protected]",
    "avatar_url": "https://example.com/wp-content/uploads/avatar.jpg",
    "profile_url": "https://example.com/profile/chris"
  }
]

Search Behavior:

Error Responses:

• 400 – Missing search term or invalid request
• 403 – Admin context without proper permissions
• 500 – Search query failed

Implementation Details:

• Uses WordPress WP_User_Query
• Wildcards applied: *term* for flexible matching
• Mentions returns a lightweight response
• Admin returns email and display name
• Artist-capable filters to users with user_is_artist / user_is_professional meta or team member status, and can exclude existing roster members via exclude_artist_id

File: inc/routes/users/search.php

Usage Examples

@Mention Autocomplete (Frontend)

// Search for users to mention
fetch('/wp-json/extrachill/v1/users/search?term=' + searchTerm + '&context=mentions')
  .then(response => response.json())
  .then(users => {
    // users = [{id, username, slug}, ...]
    displayMentionSuggestions(users);
  });

Admin User Relationship (Admin Panel)

// Find users by email for role assignment
fetch('/wp-json/extrachill/v1/users/search?term=email&context=admin', {
  headers: {
    'X-WP-Nonce': wpApiSettings.nonce
  }
})
.then(response => response.json())
.then(users => {
  // users = [{id, display_name, username, email, avatar_url}, ...]
  populateUserSelector(users);
});

PHP Example

$response = wp_remote_get(
  rest_url( 'extrachill/v1/users/search' ),
  [
    'body' => [
      'term' => 'john',
      'context' => 'mentions'
    ]
  ]
);

$users = json_decode( wp_remote_retrieve_body( $response ), true );

Usage Notes

Mentions Context:

• Designed for @mention autocomplete in community posts
• Requires a logged-in user
• Returns lightweight user data for autocomplete (includes avatar + profile URL)
• Useful for username/slug-based lookups

Admin Context:

• Designed for user relationship management
• Admin-only access for security
• Returns full user data including email and avatar
• Useful for finding users by email or display name

Artist-Capable Context:

• Designed for roster management and artist team building
• Requires logged-in user who can create artist profiles
• Filters users who can be added to artist rosters
• Excludes existing roster members when exclude_artist_id is provided
• Returns profile URL for easy access to user profiles

Performance:

• Results limited to 10 (mentions) or 20 (admin) to prevent large datasets
• Pagination not supported – use more specific search terms for narrower results

Related Endpoints:

• User Profile – Get detailed user information
• User Artists – Manage artist relationships for a user