Social Signals API

Mine your social data for commercial intent, in real time.



Social Signals API provides programmatic access to the intent-mining platform that thousands of NeedTagger customers use to mine Twitter for people who need their products, services and assistance, right now.

Our API identifies over 70 types of commercial intent in short-form user-generated text like the kind found on the most popular social networks. While optimized for Twitter, it also classifies Facebook posts, LinkedIn messages, blog comments, forum posts and other short-form text messages.

Note: Social Signals API is a data processing (classification) service, not a source of social data. We do not resell or distribute tweets. It processes social data supplied by you and returns insights in the form of document IDs and "intent tags".

How does Social Signals differ from other text analytics APIs (Clarabridge, NetBase, OpenAmplify, Alchemy, et al)?

Social Signals differs from traditional text analytics APIs in several ways:

  • We surface actionable signals of intent: Instead of classifying text for sentiment, "leads", action phrases or parts of speech, Social Signals identifies specific types of commercially relevant events ("I just got promoted") and purchase intent ("I need a new car") that any marketer can take advantage of without further processing.

  • We analyze more than text: our platform and applications can analyze more data than the body of the message to classify intent. As a result, our precision and recall (for classifying intent) are best-in-class.

  • We identify implied needs, too (for products and services): in addition to explicit statements of need ("Looking for a new crib"), our pre-engineered tags identify root causes of the need ("we're pregnant!").

  • Easy to customize: you can create your own custom Social Signals (classification filters) for any business niche, task or application using our self-service NeedTagger app. No PhDs, consultants or machine training are required. NOTE: location and profile settings will not carry-over into this API.

  • Real-time results: social data is classified in seconds.

  • Preview signal quality before committing to production: Using our self-service NeedTagger app, edit and test signals against Twitter's fire hose as often as you like. Results are presented in real-time.

What types of "social signals" does the API find?

The API identifies four types of commercial intent in a social media post. One of these, Life Events, is still in beta.

  1. Type of Need ("Intent:"). The general intention of the post without regard to a topic. Examples: Asking Questions, Complaining, Requesting Help, Scheduling and Searching.

  2. Product & Service Needs ("Product:"). A need expressed for one (or more) of 60 common product and service categories, for example: a new car, pain medication, marketing software or legal services.

  3. Life Events ("LifeEvent:" IN BETA). Important events in a person’s life such as getting married, changing jobs and moving to a new city. Life events are useful in developing a brand strategy, planning advertising campaigns and for market research. Marketing directly to life events is also an important way of selling big-ticket items such as insurance and real estate.

  4. Custom Social Signals you create ("Other:"): You may create your own custom social signals using NeedTagger's self-service customer prospecting app, which is available online at Most custom signal filters match a Type of Need with discussion topics/keywords, for example, 'Asking Questions' about 'security software'.

What percent of my social data will contain commercial intent?

It depends on the data you submit for processing. If you submit data that has been pre-filtered for commercial topics (brands, products, keywords) then you should expect 10% to 40% of the posts to include some form of intent. If your posts are not pre-filtered by topic, then the yield will probably be less than 10%.


Business applications of Social Signals include:

  • Social Sales Prospecting: identify new leads and potential customers expressing needs for your type of product/service.

  • Lead Nurturing: use Social Signals to trigger lead-nurturing emails to contacts in your Marketing Automation or CRM database.

  • Customer Support: surface complaints, questions and requests for help related to your business, brands, products and people.

  • Content Marketing: identify people requesting or needing content you've already produced.

  • Behavioral Analytics: understand the intentions and behaviors of an audience.

  • Real-Time Marketing Triggers: automatically trigger emails, score leads and send alerts in response to a person's social media behavior.

To accomplish the above, Social Signals can be fed into Marketing Automation, CRM, Customer Support and Social Media Monitoring/Analytics applications as depicted in the graphic below.

Social Signals (tags)

What signals (tags) will I receive from the API?

NeedTagger identifies up to 4 types of intent signals in every social media post submitted to it.

NOTE: If you don't see what you need below, you may create a Custom signal using our self-service NeedTagger app. Or, contact us to build a custom signal for you (for a fee).

1. Type of Need ("Intent:"):

The general type(s) of intent conveyed by the post:

  • Applying or Registering (useful in Education vertical)
  • Asking Questions
  • Betting
  • Buying
  • Complaining
  • Hungry (useful for Food Services vertical)
  • Just Arrived (useful for Travel vertical)
  • Moving
  • Needing
  • Repair Needed
  • Requesting Help
  • Scheduling or Planning
  • Searching for
  • Wishing or Wanting (aspirational)

2. Product and Service Needs ("Product:"):

The intent to purchase a specific type of product or service.

  • air travel
  • applying for college
  • baby products
  • beachwear
  • burgers
  • car repair
  • chicken
  • Chinese food
  • college
  • compact car
  • computer repair
  • content management software
  • CRM software
  • database technology
  • dentist
  • digital camera
  • environment friendly products
  • family sedan
  • fast food
  • French food
  • Greek food
  • hair salon
  • haircut
  • home appliance
  • home mortgage
  • immigration issue
  • insurance
  • Italian food
  • Japanese food
  • landed at an airport
  • LASIK surgery
  • legal issue
  • losing weight
  • marketing automation software
  • Mexican food
  • new computer
  • new mobile phone
  • pizza
  • plastic surgery
  • pregnancy
  • rental car
  • retirement facility
  • search engine optimization
  • social media followers
  • social media monitoring software
  • suffering from allergies
  • suffering from headache
  • suffering from insomnia
  • suffering from pain
  • suffering from stomach problem
  • SUV
  • tablet devices
  • teeth whitening
  • Thai food
  • truck
  • used car
  • vehicle any type
  • web servers
  • windshield repair

3. Life Events ("LifeEvent:" IN BETA):

Commercially significant events occurring in the author's life.

  • legal issues
  • pregnancy
  • major mortgage
  • losing or gaining weight
  • change in residence
  • change in schools
  • change in job
  • recently hired
  • recently promoted
  • lost job
  • seeking a job
  • + more in development

4. Custom Social Signals you create ("Other :") - OPTIONAL:

You may create custom social signals using NeedTagger's self-service customer prospecting app, which is available online at Your stream name will be returned as the tag.

How We Identify Intent

NeedTagger uses a combination of thoroughly-tested language patterns and proprietary multi-variate algorithms to classify intent. We build & test our algorithms using a mix of machine & human analysis. Many of our pre-engineered filters detect implied needs and root causes (I just injured my knee!) in addition to explicit signals (dammit, I need an MRI).

At this time, the Social Signals API analyzes the body of a post. However, our platform can analyze many more types of data to determine intent. This is how our NeedTagger application works. Other variables considered by our platform include: the context of the conversation, the author’s profile, the conversational style, the location of the post and the author, whether content sharing is involved and more.We plan to expose this additional level of intelligence in future releases.

Preparing Your Data

Data submitted to the API should adhere to the following guidelines:

  1. Minimum required data per post: every document submitted should contain at least two fields:

    • content: the body of the post (text)

    • id: a unique identifier for each document you submit (text)

  2. English language only: our API does not classify non-English posts. No results will be returned for non-English posts (we filter-out non English posts before processing).

  3. Less than 400 characters per post: posts over 400 characters may generate poor results.

  4. No more than 100 posts per call: submissions containing more than 100 posts will provide results for the first 100 posts only. The remaining posts will not be classified, and no error will be generated.

  5. You will need to filter for location and profiles separately: location and profile settings made in NeedTagger's app will not carry-over into Social Signals API filters.

Using the API

See our active API Docs to learn about our methods.

After you register your application and obtain your API Key, signup for a NeedTagger account (Free) at . Then, contact us at to obtain your NeedTagger Access Token, which you will place into every API call. In your email, please provide us with the email address you use as your NeedTagger login ID.

Social media documents should be submitted to the API in a JSON format (see example below). Your NeedTagger Access Token is required with each submission, as shown below.

Social Signals API input showing token placement (JSON format):

There are three rate-engineered API methods available to support from 1 to 100 documents per call. No more than 100 documents can be processed per API call, so larger submissions should be divided into 100-document packages.

Here is an example of social data formatted correctly for processing (required fields marked with an asterisk *):

Sample API input (JSON format):

For each document (post) processed through the API, a set of “intent tags” will be returned. These tags are human-readable. Many will be empty, indicating that no intent was detected.

Here is what a Social Signals API result looks like (JSON format):

Sample API result (JSON format)

The API will return as many social signals (tags) as it finds in each post (see lists above), PLUS tags for custom streams that the owner of the API key has created using their NeedTagger account (web or HootSuite app).

API results are returned within seconds of receiving the data submission.

Custom Signals

How do I create custom Social Signals for my business?

After obtaining your User Token and API key, there are 5 steps involved:

  1. If you don't already have one, create a Free NeedTagger account (takes 3 minutes).

  2. Create an intent-filtered Twitter stream in the NeedTagger app (free) and give it a short name. In the app you can preview & tweak the results of your custom signal filter in real-time, against the Twitter firehose. When you are happy with the filter quality, save your stream.

  3. Update the Social Signals API database with your latest Custom signal definitions by calling the /synchronize method. See API Docs for an example.

  4. Now you are ready to use your Custom signals. Post your social data to the NeedTagger API and receive results in seconds. Your Custom signal tags will appear in your results as, "Other:your stream name".

  5. Use your social signals in your application.



Although NeedTagger’s API will work fine with any type of short-form social media posts, it is optimized for Twitter.

The API processes English language posts only.

Response Codes

Over Limit Error
Authentication Failed Error
Authentication Missing Error
No Match Error

Data Sources

Social Signals API is optimized to analyze posts containing less than 400 characters of text. This covers: 100% of Twitter posts; 90% of Facebook posts and comments; most blog comments (but not full blog posts); most comments posted to community forums such as discussion groups and fan pages.

Precision and Recall

In internal tests we have seen the following precision and recall figures. These numbers are for English-language posts from Twitter that were pre-filtered for brands and products prior to submission to the Social Signals API. Posts from other social networks will score slghtly lower, on average.

Type of Intent ("Intent:"): Precision: 70-95% Recall: 80-90%

Products and Services ("Product:") & Life Events ("LifeEvent:"): Precision: 65-90% Recall: 70-90%

Custom Social Signals ("Other:"): precision and recall will depend upon the user's configuration of custom signal filters.

For example, here are the test results from a May, 2013, internal analysis of 1,000 topic-filtered tweets in the fast food, travel and automotive industries:

Recent data mining results for pre-filtered tweets (Travel, Food, Automotive verticals)

NOTE: All precision and recall numbers are calculated by comparing automated classification results against human-classified "gold standard" using the same data. Because human opinion enters into this definition, precision and recall statistics can only be used as a guideline. Your interpretation may vary.