Create an alert

POST /accounts/{account_id}/alerts

Creates a new alert for the given account.

Parameters

• account_id (string) - ID of the account

Page content

• Minimal curl example
• Available properties
• Request example
• Response example

Minimal curl example

curl -ig 'https://api.mention.net/api/accounts/{account_id}/alerts' \
    -X POST \
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
    -H 'Content-Type: application/json' \
    -H 'Accept-Version: 1.19' \
    -d '{
        "name":"ALERT_NAME",
        "query": {
            "type": "basic",
            "included_keywords":["ALERT_NAME"]
        },
        "languages":["en"],
        "sources":["web"]
    }'

Available properties

Name

name

Human readable identifier of your alert, this is the way you name it in order to remember what it is tracking.

Query

query

Query is a json object that can be of two different types: basic, or advanced. The type of a query is defined by its type attributes.

Basic query

Keywords

• included_keywords
• required_keywords
• excluded_keywords

Keywords can contains alphanumeric characters, white spaces, and the following characters: ._@#'&. Additionally, the - character is allowed when preceded by an alphanumeric character.

One of included_keywords or required_keywords MUST have at least 1 keyword in it.

Each keyword is matched exactly.

Keywords form a boolean constraint such that:

• At least one of included_keywords must be present in the mention
• And all of required_keywords must be present in the mention
• And none of excluded_keywords must be present in the mention

Monitored website

The domain acts like an included_keyword.
If block_self is set to true, it acts like a blocked_url.

Note that if a full url is provided to domain like "http://domain.com/page", input will be stripped and only domain.com will be kept.

Advanced query

Query String

query_string

A query string is composed of one or more clauses separated by AND or OR keywords. A clause can be a term (a string without white spaces in it), a quoted term (a string of characters enclosed with "), or a nested query string enclosed in parentheses.

A single clause can not contain both AND and OR at the same time: add parentheses accordingly.

this is not a querystring of the url! This is a query 'string', so an attribute of the query object, which is itself an attribute of the method.

{
    ...
    "name": "Space innovation",
    "query": {
        "type": "advanced",
        "query_string": "(space AND innovation)"
    },
    ...
}

Term

A term must contain only letters and numbers (including accented letters, and letters from any script). As an exception, a term can start with @ or # character.

Examples:

NASA
Voilà
@NASA

Wildcards

If a term contains the * or ? characters, it's a wildcard term. In a wildcard term, * matches one or more term character, and ? matches exactly one term character.

Note: not all accounts have access to wildcard terms.

Quoted term

A quoted term can contain any character. The only exception is that " or \ must be preceded by \.

Examples:

"Space Station"
"Jason-3"

Quoted terms match if all the keyword are present, in order, and next to each other.

Proximity

You can allow some distance between words by using the proximity operator ~ followed by the maximum distance allowed between each them.

The distance is the difference of the second word's position, relative to the first word, in the query and in the mention. For example, in the query "Create Alert"~1, the second word is at position 1 relative to the first one; in the mention This will create an alert, the word alert is at position 2 relatively to create. So the distance is 2-1: 1. Note that this allows words to be in opposite order if the proximity constraint is 2 or more.

The proximity can not be lower than 1, or upper than 6.

Examples:

Punctuation in quoted terms

If you expect your quoted terms to appear with and without punctuation, specify both forms in your query for best results.

Example: "Mars" AND "Rover" AND ("sand-dune selfie" OR "sand dune selfie").

Near

It is possible to specify the maximum distance between two terms or quoted terms by using the NEAR operator:

The proximity can not be lower than 1, or upper than 6.

Negation

A clause can be negated by prefixing it with the - character, or the NOT operator:

"Space Station" AND -"MIR"
"Planet" AND NOT ("Pluton" OR "Moon")

Note that there must be not whitespace after a -. Other than that, - and NOT are strictly equivalent.

Selectors

It is possible to specify that a part of the query must match only in some parts of the mention, by prefixing it with a selector. A selector is a name followed by the : character.

Examples: url:NASA, source_country:"US", source_country:(us OR ca).

Possible selectors:

Punctuation

Punctuation in quoted terms is taken into account when matching mentions.

Examples:

Restrictions

• A query string can not exceed 1700 characters (measured in unicode code points)
• An OR clause can not contain a negative clause. Example: "Space Station" OR -"MIR" is not valid.
• An OR clause can not contain a clause who consits only of one stop word. You can still match a stop word by associating it with other words in a AND clause, or in a quoted term. Examples: The OR Space Station is invalid. "The Space Station" or "The" AND "Space Station" are valid. Current list of stop words: a, an, and, at, but, by, com, from, http, https, if, in, is, it, its, me, my, or, rt, the, this, to, too, via, we, www, you.
• A query string can not consist only of negative clauses
• A term can not be longer than 128 characters (measured in unicode code points)

Languages

languages

An array of language codes. All languages that you can select as origin of the alert can be listed via the app/data request, where there is an alert language section. Currently, you are limited to 5 languages.

On alerts with query.type="advanced", the languages attribute applies only to monitored pages and reviews pages.

Countries

countries

An array of countries from which mentions should be tracked. By default, no country is "filtered out". All countries that you can select as origin of the alert can be listed via the app/data request, where there is an alert countries section. Currently, you are limited to 5 countries if you want to filter some countries out.

Note: This attribute is ignored when using advanced queries.

Sources

sources

An array of sources from which mentions should be tracked. All sources that you can select can be listed via the app/data request output, where there is an alert sources section.

In case you are using monitored_facebook_page and/or monitored_twitter_account, you have to add facebook and/or twitter to sources.

Blocked sites

blocked_sites

An array of blocked sites from which you don't want mentions to be tracked.

A mention is blocked if its URL is matched by any of the blocked URLs.

A blocked URL matches a mention’s URL if the blocked URL equals the mention’s URL, or if the mention’s URL starts with the blocked URL and is followed by one of [/.?&#].

http:// in blocked URLs also match https:// and vice-versa.

The following characters are ignored, when they appear at the end of blocked URLs: /.?&#.

Noise detection

noise_detection

We have a noise detector that strive to detect mentions that might meet your criteria, but not what you are looking for. It will watch your behaviour when you put mentions in spam and trash, and will try to skip similar mentions. It is a helper to avoid you to reach quota because of spam; but it may skip mentions you would have liked to seem from time to time.

Reviews Pages

reviews_pages

For 3 reviews website, tripadvisor, yelp, and booking, we allow you to list urls of reviews page that we will monitor.

Color

color

This defines a color to be set to the alert in dashboards, reports, etc... Available colors can be found in the colors attribute in the app endpoint.

Connection Type

connection_type

connection_type is the way this alert is related (or not) to one other. Possible values are:

• main: This is the first alert of the user created at onboarding
• related: This is a competitor alert created at the same time than the main alert
• independent: This is an alert created after and not related to main nor related

Connection Id

connection_id

connection_id is defined only for related alerts and represent the id of the main alert it is related to.

Request example

• Headers

Authorization: Bearer YOUR_ACCESS_TOKEN
Accept-Version: 1.19

• Body

{
    "name": "NASA and competitors",
    "query": {
        "type": "basic",
        "included_keywords": ["NASA", "Arianespace", "SpaceX", "Pockocmoc"],
        "required_keywords": ["mars"],
        "excluded_keywords": ["nose", "fil d'ariane"]
    },
    "languages": ["en", "fr", "ru"],
    "countries": [],
    "sources": ["web", "twitter"],
    "blocked_sites": ["www.spaceoflovemagazine.com/"],
    "noise_detection": true,
    "sentiment_analysis": true,
    "reviews_pages": ["http://www.yelp.com/biz/space-center-houston-houston-4"],
    "shares": []
}

Response example

If the request was successful, the response will return the full alert data, like if you did a GET request on that Alert.

• Body

{
    "alert": {
        "id": "112233",
        "name": "NASA and competitors",
        "query": {
            "type": "basic",
            "included_keywords": ["NASA", "Arianespace", "SpaceX", "Pockocmoc"],
            "required_keywords": ["mars"],
            "excluded_keywords": ["nose", "fil d'ariane"],
            "monitored_website": [
                "domain": "www.nasa.gov",
                "block_self": true
            ]
        },
        "languages": ["en", "fr", "ru"],
        "countries": [],
        "sources": ["twitter", "news", "web", "blogs", "videos", "forums", "images"],
        "blocked_sites": ["www.spaceoflovemagazine.com/"],
        "role": "admin",
        "stats": {
            "mention_sources": {
                "total": "0"
            },
            "mention_folders": {
                "inbox": {
                    "total": "0"
                },
                "archive": {
                    "total": "0"
                },
                "spam": {
                    "total": "0"
                },
                "trash": {
                    "total": "0"
                }
            },
            "unread_mentions": {
                "total": "0"
            },
            "unseen_mentions": {
                "total": "0"
            },
            "favorite_mentions": {
                "total": "0"
            },
            "important_mentions": {
                "total": "0"
            },
            "tasks": {
                "total": "0"
            },
            "todo_tasks": {
                "total": "0"
            },
            "done_tasks": {
                "total": "0"
            },
            "logs": {
                "total": "0"
            }
        },
        "shares": [{
            "id": "THE_ACCOUNT_ID",
            "account": {
                "id": "THE_ACCOUNT_ID",
                "name": "Doe",
                "email": "john.doe@nasa.com",
                "language_code": "en",
                "created_at": "2014-09-30T10:03:54.0+00:00",
                "updated_at": "2016-01-14T14:55:57.0+00:00",
                "avatar_url": "https:\/\/d39qsljf883l.cloudfront.net\/f6415b89ef2ljkca5c0c7d464f1b82-088f3dsqlj12lj4.jpg",
                "timezone": "Europe\/Berlin",
                "grouped_email_notification": true,
                "default_email_notification_frequency": "daily",
                "default_desktop_notification_frequency": "hourly",
                "default_push_notification_frequency": "hourly"
            },
            "role": "admin",
            "permissions": {
                "edit": true,
                "delete": true
            },
            "created_at": "2016-01-14T15:31:42.0+00:00",
            "weight": 88674800
        }],
        "noise_detection": true,
        "created_at": "2016-01-14T15:31:42.0+00:00",
        "updated_at": "2016-01-14T15:31:44.0+00:00",
        "quota_used": 0,
        "index_version": 2,
        "permissions": {
            "edit": true,
            "share": true,
            "list_tasks": true,
            "list_logs": true
        },
        "description": "Monitor NASA press release.",
        "color": "#05e363",
        "connection_type": "related",
        "connection_id": "12121212"
    }
}

Stats

Contains statistics about the alert:

• mention number by source
• mention number by folder
• tasks
• ...

Shares

Array listing who has access to the alert. When you create an alert, your account is the only item in shares; however, once the alert gets shared, all accounts it is shared with are listed in this array.

Index version

Indicates the 'search' version of the Alert. 'Search' version is a version of the search feature. For a given alert, a specific 'search' version will indicate if a specific attribute is available in the search for that Alert. In order to know which attributes are available for search for the version of your alert, check this.

Connection

connection_type is the way this alert is related (or not) to one other. Possible values are:

• main: This is the first alert of the user created at onboarding
• related: This is a competitor alert created at the same time than the main alert
• independent: This is an alert created after and not related to main nor related

connection_id is defined only for related alerts and represent the id of the main alert it is related to.