Overview Version (1) Discussion (1)

• 

  API endpoint: Find a User by Criteria

  Adds a new endpoint to the Users API controller allowing developers to retrieve a user based on one
  About this resource

  Adds a new endpoint to the Users API controller allowing developers to retrieve a user based on one of three criteria:
  

  1. user_id
  2. email
  3. username

  All parameters are optional and if more than one is specified, the search is performed against each criteria above in the order listed.
  
  For example, if all three parameters are specified and a user_id match is found, that will be returned regardless of the email or username parameters. Similarly, if the user_id is not found, but the email address is, then the user with that email address will be returned regardless of the username specified.
  
  The endpoint can be found at: GET users/find-criteria
  
  This addon was created to help me integrate my forums with my helpdesk system (HelpSpot). When viewing helpdesk requests in HelpSpot, we can perform a "Live lookup" to an external system to retrieve user data to display and/or store in the helpdesk system. In my case, I have it query my forums and return information such as usernames, user status, registration date, and even a link to their user profile on the forums.
  
  

  

  
  
  Sometimes I have a user_id, sometimes I have an email address and sometimes I have a username - so the system just sends what it has to the XenForo API and then returns the user found. Note that there is an intermediate component that translates the HelpSpot request into a XenForo API call, and then translates the user data return from XenForo into the XML format required by HelpSpot.
  
  Requirements:
  You will need an API key with the user:read scope, and if you want to retrieve email address data in the response, the API user will also need Administrator privileges with the Manage users and moderators permission.
  
  Response:
  There are two top elements in the response data returned:
  

  • user - contains the full user record as per the User data type
  • urls- a list of URLs for more information about this user:
    • api - a link to the API call to retrieve information about this user directly based on the user id (from the core API)
    • public - a link to the public XenForo profile for this user
    • admin - a link to the admin XenForo profile for this user

  Examples:
  cURL
  
  

  PHP:

  <?php
  
  $curl = curl_init();
  
  curl_setopt_array($curl, [
    CURLOPT_URL => "http://xenforo21.local/api/users/find-criteria?user_id=2&[email protected]&username=test%20user",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_TIMEOUT => 0,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "XF-Api-Key: your-api-key",
    ],
  ]);
  
  $response = curl_exec($curl);
  
  curl_close($curl);
  
  $data = json_decode($response, true);
  
  var_dump($data);

  
  Guzzle
  
  

  PHP:

      $client = new \GuzzleHttp\Client([
          'base_uri' => 'http://xenforo21.local/api/'
      ]);
  
      $response = $client->request('GET', 'users/find-criteria', [
          'query' => [
              'user_id' => 2,
              'email' => '[email protected]',
              'username' => 'test user'
          ],
          'http_errors' => false,
          'headers' => [
              'XF-Api-Key' => 'your-api-key'
          ]
      ]);
  
      $data = \GuzzleHttp\json_decode($response->getBody()->getContents(), true);
  
      var_dump($data);

  
  Laravel 7
  
  

  PHP:

      $response = \Illuminate\Support\Facades\Http::withHeaders([
          'XF-Api-Key' => 'your-api-key'
      ])->get('http://xenforo21.local/api/users/find-criteria', [
          'user_id' => 2,
          'email' => '[email protected]',
          'username' => 'test user'
      ]);
  
      $data = $response->json();
  
      var_dump($data);
• Version

  1.0.2 Stable Available Jan 25, 2026 · 0

  Download

  File size: 14 KB

  SHA-256: f24f620073f2c1b740061c483a82bdd98c2f9e6ac26308f0557e81525323f40d

  SHA-256 verified Package valid Compatibility checked Last verified: Wednesday at 12:10 AM

  Adds a new endpoint to the Users API controller allowing developers to retrieve a user based on one of three criteria:
  

  1. user_id
  2. email
  3. username

  All parameters are optional and if more than one is specified, the search is performed against each criteria above in the order listed.
  
  For example, if all three parameters are specified and a user_id match is found, that will be returned regardless of the email or username parameters. Similarly, if the user_id is not found, but the email address is, then the user with that email address will be returned regardless of the username specified.
  
  The endpoint can be found at: GET users/find-criteria
  
  This addon was created to help me integrate my forums with my helpdesk system (HelpSpot). When viewing helpdesk requests in HelpSpot, we can perform a "Live lookup" to an external system to retrieve user data to display and/or store in the helpdesk system. In my case, I have it query my forums and return information such as usernames, user status, registration date, and even a link to their user profile on the forums.
  
  View attachment 4027
  
  Sometimes I have a user_id, sometimes I have an email address and sometimes I have a username - so the system just sends what it has to the XenForo API and then returns the user found. Note that there is an intermediate component that translates the HelpSpot request into a XenForo API call, and then translates the user data return from XenForo into the XML format required by HelpSpot.
  
  Requirements:
  You will need an API key with the user:read scope, and if you want to retrieve email address data in the response, the API user will also need Administrator privileges with the Manage users and moderators permission.
  
  Response:
  There are two top elements in the response data returned:
  

  • user - contains the full user record as per the User data type
  • urls- a list of URLs for more information about this user:
    • api - a link to the API call to retrieve information about this user directly based on the user id (from the core API)
    • public - a link to the public XenForo profile for this user
    • admin - a link to the admin XenForo profile for this user

  Examples:
  cURL
  
  

  PHP:

  <?php
  
  $curl = curl_init();
  
  curl_setopt_array($curl, [
    CURLOPT_URL => "http://xenforo21.local/api/users/find-criteria?user_id=2&[email protected]&username=test%20user",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_TIMEOUT => 0,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "XF-Api-Key: your-api-key",
    ],
  ]);
  
  $response = curl_exec($curl);
  
  curl_close($curl);
  
  $data = json_decode($response, true);
  
  var_dump($data);

  
  Guzzle
  
  

  PHP:

      $client = new \GuzzleHttp\Client([
          'base_uri' => 'http://xenforo21.local/api/'
      ]);
  
      $response = $client->request('GET', 'users/find-criteria', [
          'query' => [
              'user_id' => 2,
              'email' => '[email protected]',
              'username' => 'test user'
          ],
          'http_errors' => false,
          'headers' => [
              'XF-Api-Key' => 'your-api-key'
          ]
      ]);
  
      $data = \GuzzleHttp\json_decode($response->getBody()->getContents(), true);
  
      var_dump($data);

  
  Laravel 7
  
  

  PHP:

      $response = \Illuminate\Support\Facades\Http::withHeaders([
          'XF-Api-Key' => 'your-api-key'
      ])->get('http://xenforo21.local/api/users/find-criteria', [
          'user_id' => 2,
          'email' => '[email protected]',
          'username' => 'test user'
      ]);
  
      $data = $response->json();
  
      var_dump($data);
• Discussion

  This resource has a discussion thread on the forum where you can ask questions, report issues, and talk with the author and other users.

  Join the discussion (1)