- Compatible XF Versions
- 2.1
Adds a new endpoint to the Users API controller allowing developers to retrieve a user based on one of three criteria:
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:
Examples:
cURL
Guzzle
Laravel 7
- user_id
- username
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
Code:
<?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
Code:
$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
Code:
$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);