Listed below are the required and optional fields needed to upload documents to your new custom data source. A document in this case is a Mention and its metadata, such as the Mention's text, author or date.

🚧

"items" array

All of the following required/optional fields for each document are placed within an array called items as seen in the example calls below.

Required Fields

Optional Fields

Example Call

The following call uploads two documents. The DATA_SOURCE_NUMERIC_ID value comes from the id field we noted when creating a custom data source and is entered in the contentSource field when making this request. You may also upload individual documents to a specific batch (group) of documents by adding the batch id:

curl -X POST 'https://api.brandwatch.com/content/upload' \
-H 'authorization: bearer xxxxxx-xxxxxx-xxxxxx-xxxxxx-xxxx' \
-H 'Content-Type: application/json' \
-d '
{
  "items": [
    {
      "guid": "3d101fd9b2004a11a76ba1ea637eb9f2",
      "gelocation": {
        "id": "USA.fl"
      },
      "date": "2020-03-25T15:04:00",
      "contents": "testing the data upload API",
      "custom": {
        "myfield": "testmetric"
      }
    },
    {
      "guid": "3d101fd9b2004a11a76ba1ea637eb9f3",
      "gelocation": {
        "id": "USA.pa"
      },
      "date": "2020-03-25T15:05:00",
      "contents": "testing the data upload API..again",
      "custom": {
        "npsCategory": "Promoter"
      }
    }
  ],
  "contentSource": 34354220140,
  "batch": "yourBatchIdHere-12345"
}

Here is what the response looks like:

{
    "uploadCount":2,
    "Batch":"yourBatchIdHere-12345"
}

❗️

Limits & Usage Reporting

You are limited to uploading 1,000 documents per request. The uploadCount value in the JSON response represents the number of documents you've just uploaded.

There is also a limit to how many documents can be uploaded in a 30 day/24 hour period. There two options to monitor usage which you can find in the article Usage Reporting.

Custom Fields

Each document can have a set of custom fields associated with them. These custom fields are arbitrary key value pairs that you can use to upload your own categorization for the uploaded custom data. They are mostly used for filtering documents (at the query and/or dashboard level), but can also be used in rules and tags. For example, if you upload product reviews data, you can use a custom field to upload the product rating for each uploaded review. You can use alphanumeric characters and _ in the name(s) of your new custom field(s).

{
  "items": [
    {
      "guid": "...",
      "custom": {
        "myField1": "this is some text",
        "anotherField1": "with some different text"
      }
    },
    {
      "guid": "...",
      "custom": {
        "myField2": "this is some text again",
        "anotherField2": "with some different text again"
      }
    }
  ],
  "contentSource": DATA_SOURCE_NUMERIC_ID
}

To filter your data using custom fields, you can use the custom_CustomFieldName: operator. Replace CustomFieldName with the name of your custom field and add the value of your custom field after the operator as seen in the example below:

custom_NPSCategory:Promoter

❗️

Custom Fields Limit

There is a limit of 10 custom fields per data source. As documents are uploaded, the custom fields used are tracked. If the existing field names used and the new field names in an upload would exceed 10, then you will receive an error (HTTP 400) when trying to upload the documents.