Bring Your Own Content (BYOC) Overview

In this tutorial we’ll explain how to “bring your own content” to the Meltwater platform. You can use this feature to add content of your choosing which is visible only to your company.

Before you start

To run through this tutorial, you will need:

• Your Meltwater API token
• Access to the Bring Your Own Content feature, which can be requested from Meltwater Support.

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 POST \
--url "https://api.meltwater.com/v3/imports/documents" \
--header "Accept: application/json" \
--header "apikey: **********"
--data @documents.json

For full details take a look at the Authentication page.

Example document import format

{
    "documents": [
        {
            "id": "12345",
            "url": "http://example.com",
            "timestamp": 1748272125000,
            "content": {
                "title": "Example Title",
                "subtitle": "Example Subtitle",
                "text": "Example text content",
                "duration": 120
            },
            "originPlatform": "youtube",
            "contentType": "video",
            "attachments": [
                {
                    "name": "Attachment Name",
                    "url": "http://example.com",
                    "mime": "image/png",
                    "altText": "Alt text for the attachment",
                    "type": "image",
                    "thumbnail": "http://example.com"
                }
            ],
            "source": {
                "name": "The Meltwater Times",
                "url": "http://example.com",
                "location": {
                    "countryCode": "DE",
                    "locationString": "Berlin, Germany",
                    "coordinates": {
                        "lat": 52.52,
                        "lon": 13.405
                    }
                }
            },
            "user": {
                "name": "John Doe",
                "url": "http://example.com",
                "gender": "m",
                "location": {
                    "countryCode": "DE",
                    "locationString": "Berlin, Germany",
                    "coordinates": {
                        "lat": 52.52,
                        "lon": 13.405
                    }
                }
            },
            "parent": {
                "url": "http://example.com",
                "title": "Parent Document Title"
            },
            "metrics": {
                "views": 100,
                "audience": 50,
                "ave": 4.5,
                "score": 3.2,
                "likes": 50,
                "shares": 50,
                "comments": 50,
                "replies": 50
            },
            "sentiment": "positive"
        }
    ]
}

Document fields

Notes on fields

[1] originPlatform possible values: youtube, podcasts, facebook, instagram, reddit, sina_weibo, wechat, twitter, linkedin, pinterest, twitch, tiktok, douyin, little_red_book, youku, bilibili, threads, kakaotalk, linevoom, discord, snapchat, bluesky, news_publisher, broadcast, tender_portal, reviews, blogs, forums, social_comments

[2] contentType possible values: video, comment, repost, reply, quoted, audio, post, online_press, print_press, tender, product_review, voc Note: Values must match platform-specific rules.

[3] attachments[].type possible values: image, audio, video

[4] user.gender possible values: m (male), f (female), n (other)

[5] sentiment possible values: neutral, positive, negative, unknown

JSON schema

A schema for validating individual documents is available here: BYOC JSON schema

Sending the documents

Suppose that you save a set of documents as defined above into a file named documents.json.

Then to upload that file with curl you can execute:

curl -X POST \
--url "https://api.meltwater.com/v3/imports/documents" \
--header "Accept: application/json" \
--header "apikey: **********"
--data @documents.json

Verification

If all goes well, you will receive a response providing a batch ID and a count of the uploaded documents, e.g.:

{
    "batchId": "3ccd4b7f-5987-45ca-a774-7be330763489",
    "count": 20
}

In a future release it will be possible to track the progress of your batch but for now you’ll need to check your documents in our app.

To find all documents that you have imported via this API, you can query like this:

metaData.provider.type:"byod"

To find the documents using the supplied batchId from the response, you can query like this:

metaData.applicationTags:"byod:batchId={batchId}"

If you supplied your own id field on the documents, you can find them individually like this:

externalId:{id}

Here is an example of how it might look in the Explore advanced search:

We recommend to include an id field with every document, as in general it makes it easier to reliably find it later on.

Otherwise you may need to search on some other known pieces of information from the documents (e.g. title).