About Humantic AI
Humantic AI is a pioneer in the field of predictive behavioral assessment. It combines Machine Learning & AI with Social & IO Psychology, Computational Linguistics, and Psycholinguistics to predict human behavior and personality with industry-grade accuracy, thereby creating one of the most powerful cross-domain applied research systems in the world.
It combines 25+ year old research done by Prof. James Pennebaker (UT Austin) which establishes strong correlations between linguistics and personality, with work done by Dr. Michal Kosinski (Stanford University) et all establishing correlations between social activity and behavior. It applies a combination of these approaches via a novel 'data recycling' technique to already available data and predicts the behavior, personality, and decision-making style of any individual in less than 15 seconds without requiring the individual to take a test.
Humantic AI currently serves Fortune 500 organisations like Paypal, Caterpillar, and Cognizant. The Wall St. Journal has termed Humantic AI the technology that will reshape the world, Harvard Business Review has written about its global impact and users love what it can do for them.
Beyond providing a psychometric assessment on 16 attributes which include DISC and Big Five, Humantic AI also provides powerful advanced personalization advice for two 'personas' - sales and talent.
Humantic AI For Sales
Humantic AI helps sales teams understand
prospects in a manner that wasn't possible earlier. Using Humantic AI's
cutting-edge behavior prediction AI, salespeople can know how fast a
prospect would make decisions, what factors would sway their decision, what
messaging will make them buy from you and what wouldn't, without having to
indulge in tedious research every time.
Humantic AI For Talent
Humantic AI allows Talent Acquisition and
People Analytics teams to understand a candidate's/employee's personality
and culture fit without requiring them to take a test. It allows
organisations to engage talent comprehensively via a personalized outreach, assess them
better via no-test predictive assessment, and analyze effectively via its talent
analytics suite.
Humantic AI API Customers
I've been using it for a few days now, and the accuracy of the results is just mind-blowing. I guess we'll start using this for our sales team to give them extra intel on the prospect and to help them close more efficiently.
Humantic AI just helped us close another client! The more you know!! The easier you close!
I have personally used the Humantic AI product in the area of talent acquisition and have found it very helpful.
Humantic AI APIs
Humantic AI APIs open up cutting edge predictive psychometric analytics to a wide variety of applications that need to understand their customers better to provide personalization at scale. The APIs provide a reverse-constructed profile for any individual based on the user's LinkedIn ID, email, document (like resume), or other authored text.
Humantic AI profile provides personality assessment and insights as the core output. Depending upon the input, the additional attributes could include demographics, socio-digital activity, behavioral factors, interests, and use-case specific 'personas' that include communication advice for various business scenarios. In v1.0, Humantic AI supports ‘Sales’ and ‘Hiring’ personas.
All profile attributes are determined deductively and predictively from a multitude of activity patterns, metadata or other linguistic data inputs. All attributes part of the response, unless otherwise listed as beta, have an accuracy between 80-100%.
Note: In case of any queries, please contact us at connect@humantic.ai
Resource URL:
https://api.humantic.ai/v1/user-profile
Create endpoint:
https://api.humantic.ai/v1/user-profile/create
Fetch endpoint:
https://api.humantic.ai/v1/user-profile/
Version:
1.0
|
apikey
mandatory |
Identifies the subscriber making the call to the APIs as each subscriber is assigned a unique key. Rate limits, identification and quota measurement are governed by this param value |
|
id
mandatory |
Individual (or document) identification is provided using this param value for creating the relevant Humantic AI personality profile.
The following are the types of values this param can accept for creating a profile
Request Body:
Body Param:
Key: document,
Value: <document_file> For Free-form text based analysis
Request Body:
Body Param:
{ "text": {the_text_for_the_analysis_comes_here} } Note:
|
|
firstname
optional |
First name of the individual for whom the subscriber is trying to create a profile. It can be provided with any kind of 'id', but it is actually helpful only when provided with email ID. When provided with email ID, it helps Humantic AI determine more accurately who the individual could be. |
|
lastname
optional |
Last name of the individual for whom the subscriber is trying to create a profile. It can be provided with any kind of 'id', but it is actually helpful only when provided with email ID. When provided with email ID, it helps Humantic AI determine more accurately who the individual could be. |
|
doctype
optional |
Valid values: resume When provided, Humantic AI would understand that the document being uploaded is a resume and try to analyze Linkedin data if it locates a Linkedin URL in the document. |
|
stateless
optional |
When set to true, the input text or document is not saved by Humantic AI. Applicable only when input data consists of text or document, does not apply otherwise. |
|
enrichprofile
optional |
Applicable only for the 'Special' plan subscribers when they use email ID as the 'id'. When set to false, Humantic AI would not try to auto-resolve the provided email ID to an associated social profile. By default (or if set to true), it will try to resolve the provided email ID to a social profile and use the data from the social profile as the input (for all calls where text or document is not the input type) or increase the confidence of the output (for all calls where text or document is being uploaded). |
|
analysistype
optional |
Applicable only where text or a document (including resume) in English is the input and the goal is to use Humantic predicted DISC, Big 5 or other scores and insights for hiring or talent assessment. In that case, this param should be set to "analysistype=talent" Doing so would ensure that the analysis is processed by a specialized ML algorithm that is custom-built for the talent assessment scenario and can process a resume, cover letter, or hiring related questions with high accuracy. It is applicable only if the input language is English. If the input is text or a document and either the language is not English or the goal is to do personality assessment for a non-talent scenario (for brand analysis for example), then this param should not be passed so that the analysis can be done by a standard algorithm. If the input is of any other type, then this param should not be passed. |
| apikey mandatory |
Identifies the subscriber making the call to the APIs as each subscriber is assigned a unique key. Rate limits, identification and quota measurement are governed by this param value |
| id mandatory |
This value is the same as the ‘id’ param that was provided when the analysis was created. |
| persona optional |
This param is used to obtain the results for a particular persona type while requesting the Humantic AI profile of the individual (or a document/body of text). Multiple persona values can be supported using comma as a delimiter.
Possible values: sales, hiring |
|
override
optional |
When set to true, Humantic would bypass its internal limit of minimum 300-word input and start returning results even when the input data has less than 300 words. The results are likely to be inaccurate in this case, so it should be used with utmost care. |
|
apikey
mandatory |
Identifies the subscriber making the call to the APIs as each subscriber is assigned a unique key. Rate limits, identification and quota measurement are governed by this param value |
|
id
mandatory |
Use the same id used for creating the analysis.
For providing additional text related to an earlier analysis Use form-data in the body of the request to add more text
Request Body:
Body Param:
Key: text,
Value: <additional_text_input> For uploading a document related to an earlier analysis
Request Body:
Body Param:
Key: document,
Value: <document_file> Once the data is successfully uploaded, the analysis state will change to ‘processing’. Once it's successfully processed, you can use the endpoint for fetching to retrieve the analysis with improved confidence. |
Create Analysis: For ProfilesCreate Analysis: For Document Based InputCreate Analysis: For Text Based InputFetch AnalysisCreate Analysis: For ProfilesCreate Analysis: For Document Based InputCreate Analysis: For Text Based InputFetch AnalysisCreate Analysis: For ProfilesCreate Analysis: For Document Based InputCreate Analysis: For Text Based InputFetch AnalysisCreate Analysis: For ProfilesCreate Analysis: For Document Based InputCreate Analysis: For Text Based InputFetch AnalysisCreate Analysis: For ProfilesCreate Analysis: For Document Based InputCreate Analysis: For Text Based InputFetch Analysis |
| persona |
Based on the value provided for ‘persona’ in the fetch API call i.e hiring or sales, the value of the attribute is set. For both ‘hiring’ and ‘sales’ personas, communication advice is provided tuned for the context. ‘communication_advice’ is an object type and has the following attributes
‘Description’:
The value describes the individual (or the document/body of text) analyzed. For each persona, the description is tuned to fit the persona context
For ‘hiring’ persona, the response will have an attribute called
“behavioural_factors“ that provides traits of the candidates
that will be helpful while evaluating them.
For ‘sales’ persona, the response will have an attribute called ‘key_traits’’ that provides the prospect’s buying traits relevant during the sales process
|
||||||||||||||||||||||||||||||
| personality_analysis |
An in-depth look into the personality of the individual (or the document/body of text): DISC Assessment ’Dominance’: Dominance reflects how goal and task-oriented a person is and their ability to accomplish results, irrespective of how demanding the circumstances might be. Those scoring high tend to be motivated by winning, competition and success and can be described as direct, demanding and strong-willed. ’Influence’: Influence reflects the degree to which a person prefers to work by influencing or persuading others. Those scoring high tend to be people-oriented, are motivated by social recognition and building relationships and can be described as warm and enthusiastic in general ’Steadiness’: Steadiness reflects the degree to which a person is likely to focus on cooperation, support and taking everyone along. Those scoring high tend to be consistent and calm, are excited about the opportunity to collaborate and partner and could sometimes be indecisive or overly accommodating ’Calculativeness’: Calculativeness reflects the degree to which a person is likely to be cautious, systematic and analytical. Those scoring high tend to emphasize quality and accuracy, enjoy showing off their expertise or challenging assumptions but can sometimes overanalyze things and be overcritical. Possible values for DISC
Ocean Assessment ’Openness’: Openness reflects the degree of intellectual curiosity, a desire to seek new experiences and a preference for novelty and variety. Those scoring high tend to be inventive, curious and open to trying new things whereas those scoring low tend to be consistent, cautious and more realistic in their approach. ’Conscientiousness’: Conscientiousness reflects the degree of self-discipline, focussing on doing things in a planned manner and acting dutifully. Those scoring high are usually efficient, organized and focused whereas those scoring low tend to be easy-going, spontaneous and unreliable at times. ’Extraversion’: Extraversion reflects the degree of assertiveness and sociability that an individual exhibits. People scoring high on extraversion tend to be outgoing, energetic and talkative whereas those scoring tend to be reserved, quiet and thoughtful, especially in social settings. ’Agreeableness’: Agreeableness reflects the degree of compassion, cooperation and general friendliness in a person. Those scoring high are mostly even-tempered, pleasant and easy to convince whereas those scoring low tend to challenge and question things and are likely to have a contrarian attitude. ’Emotional Stability’: Emotional Stability refers to the degree to which one can experience unpleasant emotions like anger, anxiety, etc. easily. Those scoring high tend to be calm, stable and are not perturbed easily whereas those scoring low can be passionate, excitable and have low impulse control, especially under stressful circumstances. (Emotional Stability is same as Neuroticism rated on a reverse scale) Possible values
|
||||||||||||||||||||||||||||||
| first_name |
First name of the individual for whom the analysis was requested (if applicable). | ||||||||||||||||||||||||||||||
| last_name |
Last name of the individual for whom the analysis was requested (if applicable). | ||||||||||||||||||||||||||||||
| work_history |
The employment history of the individual (if applicable) lists out the names of the companies where the individual has worked and the respective tenures. | ||||||||||||||||||||||||||||||
| photos |
Lists out the URLs of the individual’s photos on various public social platforms | ||||||||||||||||||||||||||||||
| social_profiles |
Social profile details (profile type, URL of the profile, no. of followers, etc.) of an individual (if applicable). | ||||||||||||||||||||||||||||||
| last_modified |
Specifies the last date when the information was fetched for this profile | ||||||||||||||||||||||||||||||
| education |
Provides a detailed breakdown of the individual’s education history- lists out the names of the schools, colleges or institutes from where the indivudal has pursued his/her education, with respective tenures. | ||||||||||||||||||||||||||||||
| user_name |
Social username | ||||||||||||||||||||||||||||||
| user_id |
Social user ID | ||||||||||||||||||||||||||||||
| display_name |
Name provided on social profile | ||||||||||||||||||||||||||||||
| user_description |
Description provided on social profile | ||||||||||||||||||||||||||||||
| user_profile_image |
Profile image provided on social profile | ||||||||||||||||||||||||||||||
| social_activity |
Social activity: Detailed analysis of the social post patterns and social profile of the individual (if applicable) ’Total social posts’: Total social posts by the individual in the given period ’User authority’: A metric that provides a measure of the influence that the individual has on social media. It takes into account their social posts volumes, reach, the reach of their followers, how widely appreciated and shared their social posts are, the originality of the content they share, etc. It uses a 1-10 scale, with 10 being the individuals with the highest influence. ’Social repost count’: Number of times the individual’s posts have been reposted ’Original social posts count’: Number of original social posts put out by the individual ’Followers’: Number of handles that follow the individual ’Favorite count’: Number of times the individual’s posts have been favorited ’Following’: Number of handles the individual follows ’Follower growth’: Daywise growth of followers for the past month and monthwise before that, up to the date the analysis was first done on the individual. Most of the attributes above are populated when the analysis is created using a social handle |
||||||||||||||||||||||||||||||
| interests |
Find out what the user finds interesting on social
media: ’Interest’: The areas that the individual is interested in ’Count’: Number of entities within the interest area that the individual follows ’Share’: The percentage share of this area among the total interests of the individual ’Sub Interests’: Sub-areas within the interest ’Names’: Individual names of entities the individual is interested in Note: This attribute is populated when the analysis is created using a social handle |
||||||||||||||||||||||||||||||
| content_affinity |
Find what kinds of content the individual shares the most:
’Vocab’: This provides a detailed breakout of various parts of speech the individual uses and the relative counts. It provides interjection, discrepancy word, preposition, adjective, verb, adverb, determiner, noun and pronoun counts for the individual. ’Entity types’: Provides relative counts of types of entities that the individual references most often and instances of each e.g., entity type: 'politician' and entity: 'Barack Obama'. For each entity type, the qualified entities contain instances of the type and also contain count, sentiment and percentage share of the entity within that type. ’Other topics’: Provides counts for other topics the individual mentions most often with the count and sentiment numbers for each. ’Categories’: Provides relative counts of categories that the individual references most often and sentiment associated with each. For each category, the entities contain the topics mentioned within the category and also contain count, sentiment and percentage share of the topic within that category. Note: This attribute is populated when the analysis is created using a social handle |
||||||||||||||||||||||||||||||
| demographics |
Provides a detailed demographic breakdown of the individual including gender, age, employment status, parental status, marital status, profession and location. Note: This attribute is populated when the analysis is created using a social handle |
||||||||||||||||||||||||||||||
| tech_usage |
Provides a breakdown of apps used by the individual as well as the devices owned and the number of instances they were used. Note: This attribute is populated when the analysis is created using a social handle |
||||||||||||||||||||||||||||||
| social_interactions |
Provides a list of other social users that the user interacts with,
the count of the interactions and the
sentiment associated. Note: This attribute is populated when the analysis is created using a social handle |
||||||||||||||||||||||||||||||
| related_entities |
Provides a list of the various topics that the given individual has
conversed about. ’Count’: No. of times a particular topic/user has been mentioned ’Share’: share of voice for a particular topic or user mention ’user_mention/topic’: name of the topic or social handle of the mention ’negative_sentiment’: percentage of negative sentiment towards this topic/user mention ’positive_sentiment’: percentage of positive sentiment towards this topic/user mention ’neutral_sentiment’: percentage of neutral sentiment towards this topic/user mention Note: This attribute is populated when the analysis is created using a social handle |
||||||||||||||||||||||||||||||
| languages |
Lists out the languages used by this user in various postcodes: code
for different languages, for ex:
en, fr etc. ’Percent’: usage percentage of the language ’Language’: name of the language Note: This attribute is populated when the analysis is created using a social handle |
||||||||||||||||||||||||||||||
| mood |
Depicts the percentage values for four different moods, namely-
action, anxiety, calm, depression Note: This attribute is populated when the analysis is created using a social handle |
||||||||||||||||||||||||||||||
| websites |
Lists out the various websites associated with the individual | ||||||||||||||||||||||||||||||
| metadata |
Humantic AI API returns information about the analysis request under "metadata".
Confidence Provides the confidence score with which Humantic AI is predicting the scores. Any profile with a confidence score of less than 50% will not return personality results by default, as the social data available for the particular profile is not enough to predict the scores. If necessary, results can be obtained even if the confidence score is below 50% by passing override=true in the 'fetch' call. However, it is not recommended as the results could be inaccurate. Status Code The returned status codes can fall in the following ranges:
2 : In case of success status: FOUND analysis_status: COMPLETE 11 : In case of success but with confidence below 50% (this would happen only if override=true in the API call) status: FOUND analysis_status: COMPLETE 21 : In case the profile is still under analysis, it could either have been found or still being determined. status: FOUND/NOT_FOUND analysis_status: IN_PROGRESS 29 : In case there is not enough data available for the algorithm to predict with at least 50% confidence status: FOUND/NOT_FOUND analysis_status: INSUFFICIENT_DATA
31 : In case more than 10,000 words are submitted in one API request, Humantic AI processes the request but considers only the first 10K words for the analysis. In this case, status code 31 is returned. It applies both for text and document upload. 41 : In case the provided ID does not have any relevant data and the analysis has been completed status: NOT_FOUND analysis_status: NOT_FOUND 42 : In case the provided ID does not have any relevant data and the analysis has not been completed status: NOT_FOUND analysis_status: NOT_COMPLETE 51 : In case of missing API Key status: ERROR 52 : In case of Invalid ID provided status: ERROR 53 : In case of no ID provided. No email or any other user id provided in the request status: ERROR 55 : In case of invalid API key status: ERROR 57 : In case of server error. This request has been dropped. Please contact help@humantic.ai status: ERROR 58 : In case of IP access blocked to HumanticAI status: ERROR 60 : In case you or your organisation have chosen not to access insights for a location the provided ID is determined to be from status: ERROR 61 : This ID/individual has opted for not being analyzed by Humantic AI. status: ERROR 62 : In case of invalid userids provided in the request status: ERROR 63 : Your subcription has been deactivated by admin status: ERROR 64 : No subscription found associated to this userid status: ERROR 66 : Quota reached for the API key status: ERROR 67 : Requested Endpoint doesn't exist status: ERROR 68 : Error in file upload status: ERROR 69 : Please provide both ID1 and ID2 for analysis status: ERROR 403 : In case your current plan does not allow you to perform the requested analysis. status: ERROR 445 : In case someone has flagged a profile for review. The results are not returned till a manual review has been conducted. status: ERROR 446 : In case you or your organisation have chosen not to access insights for a location the provided ID is determined to be from status: ERROR 447 : This ID/individual has opted for not being analyzed by Humantic AI. status: ERROR |
Create ResponseFetch Response |
Quota
Developers can find the usage quota of their API key from the ‘usage_stats’ attribute. This attribute will be returned in both ‘create’ and ‘fetch’ API responses.
For Eg:
Rate Limits
The current API version v1.0 supports the following rate limits:
(For standard and advanced plans only, Special plan allows for double the calls mentioned below.)
During Profile Creation:
- When the input is text or document: more than 20 calls in 2 minutes or more than 100 in 10 mins will trigger a warning via email
- When the input is text or document: more than 30 calls in 2 minutes or more than 150 in 10 mins will get your key blocked for 30 minutes (and successively increase for further violations)
- When the input is email ID, Linkedin URL or others: more than 20 calls in 2 minutes or more than 50 in 10 mins will trigger a warning via email
- When the input is email ID, Linkedin URL or others: more than 30 calls in 2 minutes or more than 100 in 10 mins will get your key blocked for 30 minutes (and successively increase for further violations)
During Profile Fetch:
- In all cases: more than 50 calls in 2 minutes or more than 100 in 10 mins will trigger a warning via email
- In all cases: more than 100 calls in 2 minutes or more than 200 in 10 mins will get your key blocked for 30 minutes (and successively increase for further violations)
Important Note: Subscribers making more calls than the above-mentioned limits could get their API Keys blocked.
FAQs
Pricing shows a monthly cost and a per-profile cost. Is the per-profile cost an add-on to the monthly price? No, there is no fixed fee or setup cost. The monthly pricing already includes a certain no. of profiles, it's not an add-on price. As you access more profiles, the cost goes up proportionately.
How is the number of profiles for each subscriber counted? For example, how will two fetch calls to the same profile be charged? Profiles are counted monthly. So if you fetch the same profile within the same month, you would be charged only once. But if you fetch the same profile next month, it would be charged again. The recommended practice is that subscriber should store the profile on their side and set it to refresh only every 6 months.
If multiple calls are made for the same profile, will the analysis reflect changes to the profile over time? Every profile is updated every 6 months (personality is proven to evolve but not very fast). So changes to scores will follow the 6 monthly frequency.
We would like to compare results obtained from the Humantic API to the IBM Watson API. How can we do that? If you already have access to Watson API, you can simply compare results from both APIs. You should expect some differences in absolute scores as both products seem to build population distributions differently. However, once you analyze the results by sub-dividing them into 5 or 3 groups, the results tend to become more similar. A vast majority of our customers find that accuracy actually moves up with Humantic AI, see here for full comparison.
The API returns numerical scores for each personality trait in the DISC and OCEAN assessments. How are these results interpreted (ie. what scale is being used to determine the "level" of each trait)? All attributes are scored on a 100 point index. However, the results are on a scale of then, with one decimal position. The levels shared by us should be taken as indicative, you should create different classes in case the default grouping doesn't work for your product.
I have just started integrating with Humantic AI APIs, are there some best practices that you'd recommend? Definitely.To build a robust integration, these are the most important scenarios that you should handle. 1. You should handle different response codes (see metadata under Response Structure), especially those with status codes in the 20-40 range. 2. You should honor the rate limits. We take them seriously and your application can temporarily get blocked if you exceed the prescribed rate limits. 3. When creating a request, you should try to use various optional params, as relevant. This will help you get better results (especially if you are providing email ID as input). 4. Profile fetching should be done with the 30-45 second gap after creating, as documented in the section on fetching profiles. Otherwise, you will be wasting a part of your quota for no reason. 5. You should try to use the code samples provided by us, it will speed up your integration. However, the code samples would not cover all scenarios that might be relevant to your requirement, so use them as a starting point in your integration and not as an end-point. 6. If your use-case requires high precision, then factor in the 'confidence_score' in the API response and provide additional data to improve confidence, if required. 7. Focus on making use of the 'personality_analysis' and 'persona' parts in the API response. The other parts are not always present, at least at this time.
21 Day FREE Trial. No Credit Card Required.
Personalise every interaction.
Standard
Improve Your Conversion
Starts from
21-day free trial. No card needed.
Advanced
Improve Your Conversion
Starts from
21-day free trial. No card needed.
Special
Improve Your Conversion
Starts from
21-day free trial. No card needed.