Search via Custom Fields
Use Case
Searching in Brandfolder is an incredibly powerful tool and works the same via the API as it does in the Brandfolder UI. One of the more frequently used searches is custom fields.
Custom fields provide a controlled taxonomy tool by adding key/value pairs to your assets. With controlled custom fields that support both single and multi-values, Brandfolder users have what they need to ensure that their asset data is maintained so that it works with the ecosystem of tools and data that you use every day. Better control means better health and accuracy of your digital asset management taxonomy.
Before you Begin
When making requests through the Brandfolder API there are a few items or requirements to keep in mind.
1. The first is authorization headers. For every single request you will need to pass an authorization header in the following format:
Headers: {“Authorization”: “Bearer <api_key>”}
2. The second item is your API key. In the authorization header you will notice that you will also need your API key. To obtain the API key visit: https://brandfolder.com/profile#integrations
3. Finally when using search via the API it’s important to keep formatting requirements in mind. Including a search parameter in an API call will require a properly formatted URL. You can find specific search parameters in the Searching Knowledge Base article. For our example we will be using custom_fields. You can also input the search the same way as you would in the UI and use a URL formatter to make sure you get the desired format.
API Workflows
These are the steps you will need to take to search custom fields via the API.
1. The first is building the Base URL
2. Second is determining the Brandfolder ID
3. Third is adding the Custom field syntax
4. Fourth is creating the syntax for searching multiple custom fields
We will be using the Sonata travel companies Brandfolder as our example while navigating each of the API Workflow steps. Our goal is to locate all of the assets with a certain custom field in this specific Brandfolder.
1. The first step is locating and using the Brandfolder Base URL
All V4 requests are made through the following Base URL:
https://brandfolder.com/api/v4 + resource endpoint.
2. Since you are wanting to locate all of the assets with a certain custom field in the Sonata Brandfolder. The second step is determining the Brandfolder ID.
When using examples in your code, you will need to GET /brandfolders/{brandfolder_id}
And use the returned slug to link to the Brandfolder you desire to search in.
https://brandfolder.com/api/v4/brandfolders/{brandfolder_id}
Once we have our brandfolder, we’ll need to include assets as well. You can do this by adding the assets endpoint to the end of the call.
https://brandfolder.com/api/v4/brandfolders/{brandfolder_id}/assets
A correct response will look like this - note that the pagination is returning a limited number of results
Response:
{
"data": [
{
"id": "<asset-id>",
"type": "generic_files",
"attributes": {
"name": "Social Desert Oasis Background",
"description": null,
"thumbnail_url": "<url>",
"approved": true
}
},
{
"id": "<asset-id>",
"type": "generic_files",
"attributes": {
"name": "Beachside Relaxation",
"description": null,
"thumbnail_url": "<url>",
"approved": true
}
},
{
"id": "<asset-id>",
"type": "generic_files",
"attributes": {
"name": "Scenic Train Rides",
"description": null,
"thumbnail_url": "<url>",
"approved": true
}
},
{
"id": "<asset-id>",
"type": "generic_files",
"attributes": {
"name": "Ocean Background",
"description": null,
"thumbnail_url": "<url>",
"approved": true
}
},
],
"meta": {
"current_page": 1,
"next_page": null,
"prev_page": null,
"total_pages": 1,
"total_count": 25
}
}3. Next, add the Custom Field syntax as a parameter.
Brandfolder allows filtering of assets based on certain custom field values. The syntax you will want to use is
?search=custom_fields.{custom_field_key_name}:"{custom_field_value}"
In our example we want to search for all assets that we include in our E-Mail campaigns. Therefore the custom field key, “Channel”, and the custom field value “E-Mail” is what we will want to search on.
?search=custom_fields.Channel:"E-Mail"
The final search call will then be: https://brandfolder.com/api/v4/brandfolders/{brandfolder_id}/assets?search=custom_fields.Channel:"E-Mail"
Response:
{
"data": [
{
"id": "<asset-id>",
"type": "generic_files",
"attributes": {
"name": "Social Desert Oasis Background",
"description": null,
"thumbnail_url": "<url>",
"approved": true
}
},
{
"id": "<asset-id>",
"type": "generic_files",
"attributes": {
"name": "Beachside Relaxation",
"description": null,
"thumbnail_url": "<url>",
"approved": true
}
},
{
"id": "<asset-id>",
"type": "generic_files",
"attributes": {
"name": "Scenic Train Rides",
"description": null,
"thumbnail_url": "<url>",
"approved": true
}
},
],
"meta": {
"current_page": 1,
"next_page": null,
"prev_page": null,
"total_pages": 1,
"total_count": 3
}
}4. Let’s say that we want to search not only for our assets associated with E-Mail campaigns but also those assets that are specific to a vacation destination.
We would repeat the steps above but also add on the custom field key “Destination” and the custom field value “Banff”.
https://brandfolder.com/api/v4/brandfolders/{brandfolder_id}/assets?search=custom_fields.Channel:"E-Mail"%20AND%20custom_fields.Destination:"Banff"
Note the URL encoding between the two custom fields. Brandfolder search syntax supports multiple methods of joining queries, just ensure that the query is URL encoded so it functions correctly in our API call.
Response:
{
"data": [
{
"id": "<asset-id>",
"type": "generic_files",
"attributes": {
"name": "Beachside Relaxation",
"description": null,
"thumbnail_url": "<url>",
"approved": true
}
},
{
"id": "<asset-id>",
"type": "generic_files",
"attributes": {
"name": "Scenic Train Rides",
"description": null,
"thumbnail_url": "<url>",
"approved": true
}
},
],
"meta": {
"current_page": 1,
"next_page": null,
"prev_page": null,
"total_pages": 1,
"total_count": 2
}
}That concludes the specific steps you would take to search on custom fields through the API.
Handling errors
Errors sometimes may occur while searching custom fields via the API. Common ones include:
403: This likely means that your API key does not have access to the assets.
404: This typically occurs when the custom field key or value was misspelled.
429: This occurs when the API key associated with the calls has reached our rate limit threshold.
If your search call succeeds with a 200 but returns no results, verify that the query syntax is correct and compound queries are encoded properly.