Adding non-visible user custom fields to the API

[Discourse]

This guide explains how to expose user custom field data through the API without displaying it on a user card.

Required user level: Administrator

This guide will walk you through the process of making User Custom Field data accessible via the API without displaying it on a user card. This can be useful when you need to programmatically access custom user data while keeping it hidden from general view.

Creating a User Custom Field

1. First, create your User Custom Field. For detailed instructions, refer to the guide for creating and configuring custom user fields guide.
2. Once you’ve set up your custom field, save it.
   
   

Finding the User Custom Field ID

1. Navigate to /admin/config/user-fields.json in your browser.
2. Locate your newly created custom field and note its ID number.
   
   

Configuring API Access

1. Go to your site’s admin settings.
2. Find either the public user custom fields or staff user custom fields setting:
   • Use public user custom fields if you want the data to be accessible to all API users.
   • Use staff user custom fields if you want to restrict access to staff API keys only.
3. Enter the custom field in the format user_field_X, where X is the ID number you noted earlier.
   For example, if your custom field ID is 7, you would enter user_field_7.
   
   

Accessing the Custom Field Data

Once configured, the custom field data will be included in the /u/[USERNAME].json endpoint under the “User Fields” section.

Searching Users by Custom Field Values

You can search for users based on their custom field values using the API:

1. Ensure the custom field has the “searchable” option checked in its settings.
   
   
2. Use the /directory_items.json endpoint with your query parameters.

Here’s an example API call:

https://yourdomain.com/directory_items.json?period=weekly&order=likes_received&name=SearchTerm&user_field_ids=1|2

• user_field_ids: Specify which custom fields to search (e.g., user_field_ids=5 to search only in custom field ID 5).
• name: The search term to look for in custom fields, usernames, and possibly full names.

Note: This search is not exclusive to custom fields and may return results based on username or full name matches as well.

For more details on available parameters, consult the API documentation.

Additional Resources

• Creating and configuring custom user fields
• Discourse API Docs
• Reverse engineer the Discourse API

Last edited by @MarkDoerr 2025-03-28T01:41:22Z

Last checked by @hugh 2024-07-09T11:12:48Z

Check document

Perform check on document:

[Krischan]

This is great, thanks! Is there a way to find a user by a value in a custom field via API?

[Canapin (Coin-coin le Canapin)]

Yes, using query parameters:

For example,
https://unicyclist.com/directory_items.json?period=weekly&order=likes_received&name=Flansberrium+G29&user_field_ids=1|2

Restrict the user custom fields to search by modifying the last parameter user_field_ids=1|2.
For example, user_field_ids=5 to search only in the custom field ID 5.

There are also a couple of other available parameters you can find in the API documentation (docs that don’t mention the user fields, but you can easily reverse-engineer the API.

The custom field(s) must have the searchable option checked for the query to work:

Also, note that the query will not search only in custom fields, but also in usernames and maybe full names. I think there’s no built-in feature to filter only by custom fields.