Managing Custom Fields

In this guide we’ll cover the basics of creating, updating and deleting Custom Fields in Explore+ using the API.

Note that Custom Fields are constructed as follows:

  • Custom field (with name, description and type)
    • Values (for tag fields one value, for multi-value fields multiple values)
      • Assignment rules (for each value multiple assignment rules can exist)

The API allows you to fetch, create, update and delete all levels of this structure.

Before you start

To run through this tutorial, you will need:

  • Your Meltwater API token

Authentication

You need to provide your API token when you call any Meltwater API endpoint.

You provide the API token as a header called apikey, for example:

curl -X GET \
  --url "https://api.meltwater.com/v3/searches" \
  --header "Accept: application/json" \
  --header "apikey: **********"

For full details take a look at the Authentication page.

Custom Field folders

In Explore+ folders are used to organize Custom Fields in your account. To fetch the folders configured in your account you can call the GET /v3/explore_plus/assets/custom_fields/folders endpoint:

curl -X GET \
  --url "https://api.meltwater.com/v3/explore_plus/assets/custom_fields/folders?workspace_id=none&page_size=10&page=1" \
  --header "Accept: application/json" \
  --header "apikey: **********"

The workspace_id parameter is mandatory. As explained in the Explore+ API overview, use none as the value if you want to access assets at the account-level, or a workspace id if you want to access assets in a specific workspace.

Note that the endpoint supports pagination using the following optional parameters:

  • page - the page of results to fetch. Defaults to 1.
  • page_size - the number of searches to fetch. Defaults to 10, max is 100.

Example response:

{
  "page": 1,
  "page_size": 10,
  "total": 1,
  "folders": [
    {
      "id": 123,
      "name": "My Folder",
      "num_custom_fields": 1
    }
  ]
}

Listing Custom Fields

To list your Custom Fields, you can call the GET /v3/explore_plus/assets/custom_fields endpoint:

curl --request GET \
  --url 'https://api.meltwater.com/v3/explore_plus/assets/custom_fields?workspace_id=none&page_size=10&page=1' \
  --header "Accept: application/json" \
  --header "apikey: **********"

Example response:

{
  "page": 1,
  "page_size": 10,
  "total": 30,
  "custom_fields": [
    {
      "id": 123,
      "folder_id": 456,
      "name": "My Custom Field",
      "description": "This is my Custom Field",
      "created": "2024-01-01T00:00:00Z",
      "updated": "2024-01-01T00:00:00Z",
      "type": "multi_value"
    },
    {
      "id": 456,
      "folder_id": null,
      "name": "My Custom Field 2",
      "description": "This is my Custom Field",
      "created": "2024-01-01T00:00:00Z",
      "updated": "2024-01-01T00:00:00Z",
      "type": "tag"
    },
    ...
  ]
}

Getting Custom Field details

You can fetch details for a specific Custom Field by calling the GET /v3/explore_plus/assets/custom_fields/<custom_field_id> endpoint.

curl --request GET \
  --url 'https://api.meltwater.com/v3/explore_plus/assets/custom_fields/12345?workspace_id=none' \
  --header "Accept: application/json" \
  --header "apikey: **********"

Example response:

{
  "custom_field": {
     "id": 456,
     "folder_id": null,
     "name": "My Custom Field 2",
     "description": "This is my Custom Field",
     "created": "2024-01-01T00:00:00Z",
     "updated": "2024-01-01T00:00:00Z",
     "type": "tag",
     "values": [
       {
         "id": 654,
         "name": "Value 2",
         "created": "2024-01-01T00:00:00Z",
         "updated": "2024-01-01T00:00:00Z",
         "num_rules": 2
       }
     ]
  }
}

Note that the API response gives you the values within the Custom Field, each with an ID you can use for subsequent API calls.

Creating a Custom Field

To create a new Custom Field in your account you can call the POST /v3/explore_plus/assets/custom_fields endpoint.

Currently two types of Custom Fields are supported:

  • tag - a single valued field
  • multi_value - a field with multiple possible values

As an example this request will create a tag Custom Field:

curl --request POST \
  --url 'https://api.meltwater.com/v3/explore_plus/assets/custom_fields?workspace_id=none' \
  --header "Accept: application/json" \
  --header "apikey: **********"
  --data '{
  "custom_field": {
    "name": "My Custom Field",
    "description": "my new Custom Field",
    "folder_id": 123,
    "type": "tag"
  }
}'

Example response:

{
    "custom_field": {
	    "id": 1345,
    "name": "My Custom Field",
    "description": "my new Custom Field",
    "folder_id": null,
    "created": "2025-01-01T00:00:00Z",
    "updated": "2025-01-01T00:00:00Z",
    "type": "tag",
    "values": [
      		{
        "id": 456,
       	 "name": "my Custom Field value",
        "color": "#FFFFFF",
        "created": "2025-01-01T00:00:00Z",
       	 "updated": "2025-01-01T00:00:00Z",
       	 "num_rules": 0
      }
    	]
    }
}

Note that tag-type Custom Fields will automatically be given a single value as part of their definition, but multi-value fields will not.

You can make use of the following parameters:

  • name - the name of your field
  • description - a description for your field
  • folder_id - to create the field in a specific folder in your account (defaults to creating a field in the root folder)
  • type - type of the field to create

Updating a Custom Field

To update an existing Custom Field in your account you can call the PUT /v3/explore_plus/assets/custom_fields/<custom_field_id> endpoint.

As an example this request will update a tag Custom Field:

curl --request PUT \
  --url 'https://api.meltwater.com/v3/explore_plus/assets/custom_fields/1345?workspace_id=none' \
  --header "Accept: application/json" \
  --header "apikey: **********"
  --data '{
  "custom_field": {
    "name": "My Custom Field - Updated",
    "description": "My new description",
    "type": "tag"
  }
}'

Example response:

{
    "custom_field": {
    "name": "My Custom Field - Updated"
    "description": "My new description",
    "folder_id": null,
    "created": "2025-01-01T00:00:00Z",
    "updated": "2025-01-01T00:00:00Z",
    "type": "tag",
    "values": [
      {
        "id": 456,
        "name": "my Custom Field value",
        "color": "#FFFFFF",
        "created": "2025-01-01T00:00:00Z",
        "updated": "2025-01-01T00:00:00Z",
        "num_rules": 0
      }
    ]
  }
}

Note that you cannot change the type of a Custom Field once created.

Deleting a Custom Field

To delete a Custom Field you can call the DELETE /v3/explore_plus/assets/custom_fields/<custom_field_id> endpoint with the ID of the field you wish to delete.

For example to delete the field with ID “123” in your account:

curl -X DELETE \
  --url "https://api.meltwater.com/v3/explore_plus/assets/custom_fields/123?workspace_id=none" \
  --header "Accept: application/json" \
  --header "apikey: **********"

The API will return a 204 status code if the search is deleted successfully.

Getting Custom Field Value details

You can fetch details for a specific Custom Field value by calling the GET /v3/explore_plus/assets/custom_fields/<custom_field_id>/values/<value_id> endpoint.

url --request GET \
  --url 'https://api.meltwater.com/v3/explore_plus/assets/custom_fields/12345/values/987?workspace_id=none' \
  --header "Accept: application/json" \
  --header "apikey: **********"

Example tag Custom Field value response:

{
  "custom_field_value": {
    "id": 123,
    "name": "My Custom Field Value",
    "color": "#FFFFFF",
    "created": "2025-01-01T00:00:00Z",
    "updated": "2025-01-01T00:00:00Z",
    "rules": [
      {
        "id": 456,
        "created": "2025-01-01T00:00:00Z",
        "updated": "2025-01-01T00:00:00Z",
        "query": {
          "case_sensitivity": "no",
          "all_keywords": [
            "honda"
          ],
          "any_keywords": [
            "mazda"
          ],
          "not_keywords": [
            "nissan"
          ],
          "type": "keyword"
        }
      }
    ]
  }
}

Creating a Custom Field value

To create a new value for a Custom Field in your account you can call the POST /v3/explore_plus/assets/custom_fields/<custom_field_id>/values endpoint.

Note that you cannot add a value to a tag type field. Tag type fields have a single value created automatically for you.

As an example this request will add a new value to the field with ID 12345:

curl --request POST \
  --url 'https://api.meltwater.com/v3/explore_plus/assets/custom_fields/12345/values?workspace_id=none' \
  --header "Accept: application/json" \
  --header "apikey: **********"
  --data '{
  "custom_field_value": {
    "name": "My Custom Field Value",
    "color": "#FFFFFF"
  }
}'

Example response:

{
  "custom_field_value": {
    "id": 123,
    "name": "My Custom Field Value",
    "color": "#FFFFFF",
    "created": "2025-01-01T00:00:00Z",
    "updated": "2025-01-01T00:00:00Z",
    "rules": []
  }
}

You can make use of the following parameters:

  • name - the name of your field
  • color - a color for the field as a hex value

Updating a Custom Field value

To update a value for a Custom Field in your account you can call the PUT /v3/explore_plus/assets/custom_fields/<custom_field_id>/values/<value_id> endpoint.

As an example this request will update value with ID 123 for the field with ID 12345:

curl --request PUT \
  --url 'https://api.meltwater.com/v3/explore_plus/assets/custom_fields/12345/values/123?workspace_id=none' \
  --header "Accept: application/json" \
  --header "apikey: **********"
  --data '{
  "custom_field_value": {
    "name": "My Custom Field Value - Updated",
    "color": "#FFFFFF"
  }
}'

Example response:

{
  "custom_field_value": {
    "id": 123,
    "name": "My Custom Field Value - Updated",
    "color": "#FFFFFF",
    "created": "2025-01-01T00:00:00Z",
    "updated": "2025-01-01T00:00:00Z",
    "rules": []
  }
}

Deleting a Custom Field value

To delete a Custom Field value you can call the DELETE /v3/explore_plus/assets/custom_fields/<custom_field_id>/values/<value_id> endpoint with the ID of the field and value you wish to delete.

For example to delete the value with ID “456” from field with ID “123” in your account:

curl -X DELETE \
  --url "https://api.meltwater.com/v3/explore_plus/assets/custom_fields/123/values/456?workspace_id=none" \
  --header "Accept: application/json" \
  --header "apikey: **********"

The API will return a 204 status code if the search is deleted successfully.

Creating a Custom Field Value assignment rule

To create a new assignment rule for a Custom Field value you can call the POST /v3/explore_plus/assets/custom_fields/<custom_field_id>/values/<value_id>/rules endpoint.

As an example this request will add a new rules to the value with ID 123, for field with ID 12345:

curl --request POST \
  --url 'https://api.meltwater.com/v3/explore_plus/assets/custom_fields/12345/values/123/rules?workspace_id=none' \
  --header "Accept: application/json" \
  --header "apikey: **********"
  --data '{
  "rule": {
    "query": {
      "case_sensitivity": "no",
      "boolean": "honda OR mazda",
      "type": "boolean"
    }
  }
}'

Example response:

{
  "rule": {
    "id": 456,
    "created": "2025-01-01T00:00:00Z",
    "updated": "2025-01-01T00:00:00Z",
    "query": {
      "case_sensitivity": "no",
      "boolean": "honda OR mazda",
      "type": "boolean"
    }
  }
}

Currently two types of rule are supported:

  • boolean - a rule using a boolean string query
  • keyword - a rule using simple keywords

For boolean rules you can specify:

  • query.boolean - the boolean query for the rule
  • query.case_sensitivity - specifies the case-sensitivity mode for the rule (yes = exact match, no = no case sensitive matching, hybrid = match capital letters only)

For keyword rules you can specify:

  • query.all_keywords - mentions must contain all these words
  • query.any_keywords - mentions must contain at least one of these words
  • query.not_keywords - mentions must not contain any of these words
  • query.case_sensitivity - specifies the case-sensitivity mode for the rule (yes = exact match, no = no case sensitive matching, hybrid = match capital letters only)

Updating a Custom Field value assignment rule

To update an existing assignment rule for a Custom Field value you can call the PUT /v3/explore_plus/assets/custom_fields/<custom_field_id>/values/<value_id>/rules/<rule_id> endpoint.

As an example this request will update rule with ID 456, for the value with ID 123, for field with ID 12345:

curl --request PUT \
  --url 'https://api.meltwater.com/v3/explore_plus/assets/custom_fields/12345/values/123/rules/456?workspace_id=none' \
  --header "Accept: application/json" \
  --header "apikey: **********"
  --data '{
  "rule": {
    "query": {
      "case_sensitivity": "no",
      "boolean": "honda OR mazda",
      "type": "boolean"
    }
  }
}'

Example response:

{
  "rule": {
    "id": 456,
    "created": "2025-01-01T00:00:00Z",
    "updated": "2025-01-01T00:00:00Z",
    "query": {
      "case_sensitivity": "no",
      "boolean": "honda OR mazda",
      "type": "boolean"
    }
  }
}

Deleting a Custom Field value assignment rule

To delete a Custom Field value assignment rule you can call the DELETE /v3/explore_plus/assets/custom_fields/<custom_field_id>/values/<value_id>/rules/<rule_id> endpoint with the ID of the field, value and rule you wish to delete. For example to delete the rule with ID “879” from value with ID “456” from field with ID “123” in your account:

curl -X DELETE \
  --url "https://api.meltwater.com/v3/explore_plus/assets/custom_fields/123/values/456/rules/789?workspace_id=none" \
  --header "Accept: application/json" \
  --header "apikey: **********"

The API will return a 204 status code if the search is deleted successfully.