- Compatible XF 2.x versions
- 2.1
- 2.2
- License
- MIT
- Visible branding
- No
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:
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
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-criteriaThis 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 typeurls- 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 useradmin- 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=test@example.com&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' => 'test@example.com',
'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' => 'test@example.com',
'username' => 'test user'
]);
$data = $response->json();
var_dump($data);- Related resources
- Tutorial: How to call the XenForo API
