Intro – Welcome to Sentino API!

Page Navigation Menu

1. General Info
   – API Operation Levels
   – Authentication
   – Supported Languages
2. Use Cases
   – Big 5 traits from a text
   – NEO traits from a questionnaire
   – Questionnaire for Big 5 and Neo
   – Managing Profiles
3. Scoring
   – Metrics
   – Score Text
   – Score Answer
   – Score Interview
   – Score Inventory
   – Score Items
4. Scoring
   – Metrics
   – Score Text
   – Score Answer
   – Score Interview
   – Score Inventory
   – Score Items
5. Person
   – Set Up a Profile
   – Create a Person
   – Add Items
   – Person Profile
   – Delete a Person
6. Inventory List
   – Inventories
   – Inventory Items
   – Index Items
7. Chatbot
   – Create Link
   – Start Link
   – Get Messages
   – Reply
   – Complete Link
   – Get Report
   – Stop Link
8. Questionnaires
   – Questionnaire
   – Create a Questionnaire
9. Item Analysis
   – Item Classification
   – Item Projection
10. Errors

A psychological personality API is a type of application programming interface (API) that allows developers to integrate personality assessments into their applications. This type of API is based on psychological theories of personality. Personality is a complex and multifaceted concept, and there are many different theories and approaches to understanding it. A psychological personality API allows developers to incorporate these theories and assessments into their applications, providing users with a way to assess and understand their own personality traits or those of others. This can be useful for a variety of purposes, including self-improvement, career development, and relationship building. Sentino Personality API is a data-driven, AI-powered service built to provide insights into human personality.

Please note that, as a matter of principle, we anchor our testing methodology on the International Personality Item Pool (IPIP), a comprehensive public domain collection of personality-related items that can be used for psychological testing purposes. The IPIP is managed by the Oregon Research Institute and consists of over 3,000 items and more than 250 scales. These items have been constructed from the pool and are freely available for use. Researchers, practitioners, and anyone interested in personality assessment can access and utilize these items in personality tests without asking for permission or paying any fees.

Personality inventories proposed by Sentino are constructed based on the IPIP item collection and may slightly differ from their official versions. If you’re interested in exploring the IPIP items and scales, you can find them on the official IPIP website. Remember that no personality tests are administered directly on that site; it’s purely a resource for accessing the items and scales.

We have integrated vast psychological data and built a natural language interface for it. We have trained our models using the state-of-art NLP stack (e.g. Spacy, Transformers). This representation links the text to 20+ widely known validated inventories (Big 5, NEO-PI, RIASEC, ORVIS, ORAIS, DISC, etc.; the list can be further supplemented). We continuously keep researching and updating the models, striving for high accuracy.

That is why Sentino API is capable of analyzing various data sources (calls, messages, customer feedback, CVs, chat histories, surveys, forum and blog posts, and many more). Audio and video records (e.g. interviews) can also be scored following their processing with a text transcriber.

Sentino API was initially developed as a general psychological processor. This fact makes its adaptation to different application fields, industries, and verticals a rather straight-forward task.

One of the key advantages of the Sentino Personality API is its ability to process large amounts of text quickly and accurately. This means that developers can easily incorporate personality analysis capabilities into their apps without worrying about performance issues or slow processing times.

Too long to read?
Request API token and explore most common use cases!

REQUEST DEMO

If you have any data and want to explore it from a psychological perspective, Sentino API will serve you well!

All end-points of Sentino API are explained in details. You can view code examples in the dedicated highlighted areas.

General Info

The key idea of Sentino API is to transform any type of information into psychologically meaningful representation and link it to validated personality inventories mentioned above.
When using it you will be able to:

1. Transform and score text about a person (e.g. a self-description) into chosen personality inventories.
2. Transform and score items about a person into chosen personality inventories.
3. Score interview of a person (in the form of an an audio/video record) according to chosen personality inventories.
4. Score LinkedIn profile of a person according to chosen personality inventories.
5. Create a psychological profile of a person and continuously update it, by adding new information.

Sentino Personality API – Operation Levels

There are three main levels Sentino API operates on: item, inventory and person:

• item is simply a statement about one’s self that usually starts with a personal pronoun “I/My” (e.g. “I am an introvert” or “My name is Robert.”). See Item endpoints for more details.
• inventory is a set of items to measure particular traits of a person (e.g. Big-5, NEO-PI etc.). Sentino API supports a plenty of different inventories. See Inventories endpoints for more details.
• person is treated as a composition of different items. Items can be extracted from questionnaires a person fills in, a person’s self-description or in other way. Please see Scoring and Person for more details.

Start exploring the API from requesting API token and trying out most common Use Cases.

Authentication

If you haven’t got your token yet, please request it.

Sentino API uses tokens to give access to the API. You can request the token by contacting us via e-mail: info@sentino.org or through the Contact page of this website. It is free for non-commercial use and low traffic.

Sentino API expects the token to be included in all API requests to the server in a header that looks like the following:

# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
  -H "Authorization: Token sentino_api_token"

Supported Languages

Currently, two languages are supported: English and Portuguese. If you need another language, please Contact Us.

If you use other language than English, you should provide ‘lang’ parameter to most of endpoints.

Example: SentinoBot

Sentino API provides a great flexibility to fit many domains where insights on personality are important.

One of the easiest ways to explore the API is to chat with SentinoBot. This bot is an AI-powered chatting tool built to leverage a lot of API’s functionality. One can see Sentino API in action by chatting with the bot via Facebook Messenger facebook.com/sentinobot.

Use Cases

One of the most common cases where Sentino API shines is getting Big 5 or NEO traits (or any others) from a text written by a person. Please note that the text should contain psychologically meaningful information. Otherwise, the statistical confidence level will be rather low. This is why it is important to understand where the text comes from.

Further, we will discuss two scenarios that are the most common. Both scenarios imply that you don’t want to keep a personal profile in the database. If you do want to continuously work with a person’s profile by updating it, check out the next use case: managing profile.

Big 5 traits from a text

Suppose, you have a self-description of a person, kindly provided by that person or maybe you have written some passages about yourself of other person. You want to analyze the text to understand what Big 5 traits it reveals about the person.

This can be easily done using the Score Text endpoint.

NEO traits from a questionnaire

Suppose, you asked a person well-posed questions and gathered the responses. In this case, you should use another endpoint: Score Items, that will bring you much higher confidence in the final scoring. However, you should keep in mind that ideally you should use a questionnaire specially designed to measure the inventory of interest.

Questionnaire for Big 5 and Neo

Usually, you can ask a person only a limited amount of questions and want to score concrete psychological traits.

• What questions should you ask?
• What are the best questions that provide you with the maximum information?

To solve this problem, you need to perform the following steps:

1. Pick the inventory you are interested in. For example, NEO.
2. Create a questionnaire by choosing a number of questions you intend to ask a person.
3. Collect the data from a person, simply by asking a person these questions.
4. Build a psychological profile. Use Score Items.

Managing Profiles

This is a scenario in which you want to keep a psychological profile of a person up to date. You can easily keep adding new information (items) and get the profile updated.

These are the actions to be performed:

• Create a person. You will simply get an ID to operate with
• Add “items” about a person (like self-description or item-response pairs)
• Get person’s profile based on Big5, NEO, or other inventories (depending on your needs)
• Add more items in the similar way
• Get the profile automatically updated
• Delete a profile if you do not plan to use it anymore

The ability to update a profile based on new items makes adding new information absolutely price-efficient. Within the commercial plan, you only pay for the newly added text.

When you delete a person, no personal information is kept any longer (for commercial plan).

Scoring

Endpoints presented here are aimed to transform textual information about a person into psychologically meaningful representation. For example, if you have a description of a person or answers to psychologically meaningful questions, you can understand what traits (Big 5 and others) a person possesses.

Metrics

Each scoring consists of the metrics discussed below.

If you need to track one person over a long time period, it is more reliable to use score. Keep an eye on the confidence. If it is “very low”, normally it means that results should be taken with a grain of salt.

1. Score Text

Using this endpoint, you can easily extract psychologically meaningful information from a self-description of a person given in a natural language.

Technically, the text is split into sentences. Each sentence is then labeled with a corresponding topic (see the section Item Classification) and inventory (like Big5, NEO, etc., see the section Item inventories).

In order to get a deeper understanding of this endpoint, you can try Self-Description Analysis – a visual tool that gives a glimpse on it.

curl -X POST "https://api.sentino.org/api/score/text"
-H "Authorization: Token sentino_api_token"
-H "Content-Type: application/json"
-d '{
  "inventories": ["big5"],
  "text": "I am very calm and steady. I generally keep my cool in challenging situations.",
  "lang": "en"
}'

{
    "text": "I am very calm and steady. I generally keep my cool in challenging situations.",
    "inventories": [
        "big5"
    ],
    "scoring": {
        "big5": {
           "neuroticism": {
                "quantile": 0.254,
                "score": -1.0,
                "confidence": 0.310,
                "confidence_text": "normal"
            },...
    },
    "lang": "en"
}

The text data is accurately scored with the help of our AI-powered tool. You receive the applicant’s personality profile based on the BIG-5, RIASEC, NEO, BFAS or other suitable validated and globally recognized psychological scales. This profile is issued in a clearly arranged form comprising numerical score, and brief but insightful text description. Currently, we are working hard on visualization of the results obtained in a user-friendly infographic form and provision of recommendations based on scoring performed.

The data provided by our tool forms a reliable basis for making unbiased personality-related decisions.

2. Score Answer

This endpoint is used to extract psychologically relevant information from a person’s response to one individual question.

From a technical standpoint, the processing of such an answer is similar to text processing. The following parameters are used here:

curl -X POST "https://api.sentino.org/api/score/text"
-H "Authorization: Token sentino_api_token"
-H "Content-Type: application/json"
-d '{
  "inventories": ["big5"],
  "question": "Tell me a little bit about yourself.",
  "answer": "Ok, what can I say. I am open-minded. I really enjoy testing new ideas.",
  "lang": "en"
}'

{
    "inventories": [
        "big5"
    ],
    "scoring": {
        "big5": {
            "openness": {
                "quantile": 0.723,
                "score": 1.0,
                "confidence": 0.304,
                "confidence_text": "normal"
            },...
    },
    "lang": "en",
    "answer": "Ok, what can I say. I am open-minded. I really enjoy testing new ideas.",
    "question": "Tell me a little bit about yourself."
}

3. Score Interview

This endpoint allows getting personality insights from an interview text.

Based on prior consent, make an audio or video record of the interview with a person of interest and file this record to us. We will automate a repetitive and tedious analysis task for you. You can provide the interview for analysis either in the text form (*.txt, *.doc, *.docx) or as an original audio/video record.

The following input parameters are used for this endpoint:

curl -X POST "https://api.sentino.org/api/score/interview"
-H "Authorization: Token sentino_api_token"
-H "Content-Type: application/json"
-d '{
  "inventories": ["big5"],
  "text": "A: Are you outgoing?\nB: Not really. I prefer to spend time alone.",
  "lang": "en"
}'

{
    "text": "A: Are you outgoing?\nB: Not really. I prefer to spend time alone.",
    "inventories": [
        "big5"
    ],
    "scoring": {
        "big5": {
            "extraversion": {
                "quantile": 0.318,
                "score": -1.0,
                "confidence": 0.318,
                "confidence_text": "normal"
                }, ...
    },
    "lang": "en"
}

Please note that there are two interview text layouts currently supported by Sentino Personality AI by the default:

Layout 1.

A: How is life?
B: Life is good.
A: Really?
B: Yes.

Layout 2.

A
How is life?

B
Life is good.

A
Really?

B
Yes.

Processing options for other interview text layouts can be proposed by the request. So, if you use other standard layout, please let us know.

If we receive the interview in the form of an audio or video record, we initially use AI speech recognition tools to convert audio and video content into transcripts during the pre-processing phase and then employ the resulting text for mining.

4. Score LinkedIn profile

Please feed Sentino API with a link on the LinkedIn profile of the person of interest and use this endpoint to get valuable personality insights.

You need to use only one input parameter here:

curl -X POST "https://api.sentino.org/api/score/linkedin"
-H "Authorization: Token sentino_api_token"
-H "Content-Type: application/json"
-d '{
    "url": "https://www.linkedin.com/in/deniss-stepanovs-2248111a/"
}'

{
    "url": "https://www.linkedin.com/in/deniss-stepanovs-2248111a/",
    "scoring": {
        "big5": {
            "agreeableness": {
                "score": 0.408,
                "quantile": 0.912,
                "confidence": 0.447,
                "confidence_text": "normal",
                "beta_a": 1.912,
                "beta_b": 1.088
            },
…
        },
        "riasec": {
            "artistic": {
                "score": -0.69,
                "quantile": 0.289,
                "confidence": 0.451,
                "confidence_text": "normal",
                "beta_a": 1.289,
                "beta_b": 1.711
            },
…
        },
        "skill": {
            "active learning": {
                "score": 0.103,
                "quantile": 0.29,
                "confidence": 0.322,
                "confidence_text": "normal",
                "beta_a": 1.29,
                "beta_b": 1.71
…
        },
        "style": {
            "achievement/effort": {
                "score": 0.495,
                "quantile": 0.44,
                "confidence": 0.588,
                "confidence_text": "high",
                "beta_a": 1.44,
                "beta_b": 1.56
            },
…
        },
        "value": {
            "achievement": {
                "score": 0.043,
                "quantile": 0.175,
                "confidence": 0.155,
                "confidence_text": "low",
                "beta_a": 1.175,
                "beta_b": 1.825
            },
…
}

5. Score Inventory

This endpoint facilitates the automated processing of results obtained from respondents when they complete standardized personality questionnaires. By providing the API with the complete list of questions from a specific questionnaire and the person’s responses in either the ‘question-answer’ or ‘item-response’ format, you can receive a comprehensive quantification of the results, along with the statistical confidence level associated with each result.

The following parameters are used here:

Currently, two item types are supported here:

Here is an example of the relevant API query:

curl -X POST "https://api.sentino.org/api/score/items"
-H "Authorization: Token sentino_api_token"
-H "Content-Type: application/json"
-d '{
  "inventories": ["big5"],
  "items": [
{"item": "I am emotionally stable, not easily upset.", "response": "strongly agree"},
{"item": "I can be moody.", "response": "neutral"},
{"item": "I get nervous easily.", "response": "disagree"},
{"item": "I worry a lot.", "response": "disagree"},
{"item": "I am relaxed, handle stress well.", "response": "agree"},
{"item": "I tend to find fault with others.", "response": "disagree"},
{"item": "I am helpful and unselfish with others.", "response": "agree"},
{"item": "I am considerate and kind to almost everyone.", "response": "neutral"},
{"item": "I start quarrels with others.", "response": "disagree"},
{"item": "I have a forgiving nature.", "response": "agree"}
  ],
  "lang": "en"
}'

{
    "items": [
        "{'item': 'I am emotionally stable, not easily upset.', 'response': 'strongly agree'}",
        "{'item': 'I can be moody.', 'response': 'neutral'}",
        "{'item': 'I get nervous easily.', 'response': 'disagree'}",
        "{'item': 'I worry a lot.', 'response': 'disagree'}",
        "{'item': 'I am relaxed, handle stress well.', 'response': 'agree'}",
        "{'item': 'I tend to find fault with others.', 'response': 'disagree'}",
        "{'item': 'I am helpful and unselfish with others.', 'response': 'agree'}",
        "{'item': 'I am considerate and kind to almost everyone.', 'response': 'neutral'}",
        "{'item': 'I start quarrels with others.', 'response': 'disagree'}",
        "{'item': 'I have a forgiving nature.', 'response': 'agree'}"
    ],
    "inventories": [
        "big5"
    ],
    "scoring": {
        "big5": {
            "agreeableness": {
                "quantile": 0.703,
                "score": 0.667,
                "confidence": 0.313,
                "confidence_text": "normal"
            },
            "neuroticism": {
                "quantile": 0.232,
                "score": -0.725,
                "confidence": 0.568,
                "confidence_text": "high"
            }...
     },
    "lang": "en"
}

6. Score Items (Score Facts in v3 and earlier versions)

This endpoint holds the highest level of versatility as items serve as the fundamental building blocks, from which other intricate elements for analysis (such as larger texts, interviews, and social media profiles) are constructed. If versatility is what you seek, then this endpoint is precisely what you need.

Items

Item is a piece of information about a person. There are three types of items currently supported:

Responses

There are many ways to response to a psychological item. However, most personality questionnaires use a 7-point scale from “strongly agree” through “neutral” to “strongly disagree”. That is why internally all responses are translated into these distinct seven groups. The table shows typical synonyms to the core responses.

Item Scoring

If you have previously collected well-structured items as described above, feed the API with your items and get the psychological portrait of a person.

Please see an example of how to use this endpoint below.

curl -X POST "https://api.sentino.org/api/score/items"
-H "Authorization: Token sentino_api_token"
-H "Content-Type: application/json"
-d '{
  "inventories": ["big5"],
  "items": [
    {
      "text": "My name is John. I am 30 years old. I am an extravert."
    },
    {
      "interview": "A: Are you outgoing?\nB: Yes, sure."
    },
    {
      "question": "Tell me a little bit about yourself.",
      "answer": "Well, I am optimistic and outgoing."
    },
    {
      "item": "I do not like to chat.",
      "response": "disagree"
    }
  ],
  "lang": "en"
}'

{
"items": [
        {
            "text": "My name is John. I am 30 years old. I am an extravert."
        },
        {
            "interview": "A: Are you outgoing?\nB: Yes, sure."
        },
        {
            "question": "Tell me a little bit about yourself.",
            "answer": "Well, I am optimistic and outgoing."
        },
        {
            "item": "I do not like to chat.",
            "response": "disagree"
        }
    ],
"inventories": [
        "big5"
    ],
    "scoring": {
        "big5": {
            "extraversion": {
                "quantile": 0.790,
                "score": 1.0,
                "confidence": 0.372,
                "confidence_text": "normal"
            },...
    },
    "lang": "en"
}

Soon to come: Time Stamp

A time stamp can be indicated for each individual item. This time stamp is required to account for time persistency of an item. For example, “I am in a bad mood now” is usually constrained in time, unlike “I am usually in a bad mood”. If a time stamp is not provided, it is set to the current time by the default.

Person

In this section you can find all the available endpoints for managing psychological profiles of individuals. The advantage of using these endpoints is the ability to continuously add new information about a person and retrieve their automatically updated profile.

Please note that, prior to use of these endpoints, you need to define what inventories you want to use and get updated for each person.

All the known items about a person are stored in the database. Once any new information about this person arrives, the corresponding profile is updated. The newly updated profile can be easily read out by querying profile.

Set up a profile

In order to use person-related endpoints, you need to set up the inventories of interest. Once you run the below-mentioned query, you can start “adding people” and the results for the pre-selected inventories will get automatically updated.

curl -X POST "https://api.sentino.org/api/client/profile"
-H "Authorization: Token sentino_api_token"
-H "Content-Type: application/json"
-d '{
  "inventories": ["big5", "neo"]
}'

{
    "name": "default",
    "inventories": [
        "big5",
        "neo"
    ],
    "message": "inventories successfully added/updated"
}

Create a person

Please use the query described below to create a person. The query returns the ID of this person. All other person-related endpoints depend on this ID.

At this point no charges (even for commercial users) are applied.

curl -X POST "https://api.sentino.org/api/person/create"
-H "Authorization: Token sentino_api_token"
-H "Content-Type: application/json"

{
  "id": "dfefFdfewdfXDDf"
}

Add items

In order to add items, please execute the query described below.

Please use the ID of the previously created “person” to refer to the relevant individual. Then, provide as many items as you want.

Once the items are provided, the scoring will take place in accordance with a chosen inventory or chosen inventories. The charges (for commercial users) are applied at this particular phase. The price depends on the length of the “text” field and number of facets (traits) of the inventories you added before.

Whenever required, you can add new “items”. Subsequently, only the newly-added information is charged.

You need the following parameters to execute this query:

Currently, there are three types of supported items:

curl -X POST "https://api.sentino.org/api/person/<id>/itm"
-H "Authorization: Token sentino_api_token"
-H "Content-Type: application/json"
-d '{
  "items": [
    {
      "text": "My name is John. I am an extravert.",
      "lang": "en"
    },
    {
      "text": "I do not like to chat.",
      "response": "disagree",
      "lang": "en"
    },
    {
      "url": "https://www.linkedin.com/in/deniss-stepanovs-2248111a/"
    }
  ]
}'

{
  "id": "<id>",
  "message": "success"
}

Person profile

This endpoint allows building a personal profile from individual items.

To get a person profile (as per Big5, NEO, RIASEC, etc.) simply use the following query.

Please note:

• The correspondent inventories should be set up in advance
• If no relevant items are provided you still get a default scoring (that depends on inventory)
• No charges are applied at this point, since all the scoring was actually performed during the “item adding” phase

curl -X GET "https://api.sentino.org/person/<id>/profile"
-H "Authorization: Token sentino_api_token"
-H "Content-Type: application/json"

{
  "big5": {
        "conscientiousness": {
          ...
        },
        "openness": {
            "score": 0.0,
            "quantile": 0.5,
            "confidence": 0.1,
            "confidence_text": "low"
        },
  "via": {
      ...
  }
}

Delete a person

In order to delete a person, please run the query described below.

As the result of the query execution, the following happens:

• The “person” is deleted (the relevant ID does not work anymore)
• All the items and performed scoring are deleted
• Information related to the fact of the scoring performance with the correspondent price is kept (!)
• Information related to the query itself with the first 16 symbols (and length) of the items is kept (for debugging purposes)

curl -X DELETE "https://api.sentino.org/api/person/<id>"
-H "Authorization: Token sentino_api_token"
-H "Content-Type: application/json"

{
  "message": "success"
}

Inventory List

Inventory is a set of items that are intended for measurement of psychological traits of a person (e.g. Big-5, NEO-PI etc.)

Endpoints discussed in this section allow you to get all available personality inventories (such as Big 5, NEO etc.) together with their facets (indices) and corresponding items. These are questionnaires help to understand individuals’ psyche. Theya are reliably validated by numerous scientific studies and widely used by practitioners. The inventories listed below can be used out of the box. If you need any other inventory, please do not hesitate to contact us.

Inventories

This endpoint shows all available personality inventories.

List of inventories:

[1] Goldberg (1992). Big-Five Factor Markers

[2] DeYoung, Quilty, and Peterson (2007). 10 Big-Five Aspects

[3] Costa and McCrae (1992). NEO-PI-R

[4] Hofstee, de Raad and Goldberg (1992). 45 AB5C facets

[5] Lee and Ashton (2004). HEXACO-PI

[7] Markey and Markey (2009). 8 IPIP Interpersonal Circumplex Scales

[8] Saucier (1997). 7-factor scales

[9] Gough (1996). California Psychological Inventory

[10] Barchard (2001). Potential “Emotional Intelligence” Components

[11] Hans Eysenck & Sybil Eysenck (1975). Eysenck Personality Questionnaire

[12] Jackson (1994). Jackson Personality Inventory

[13] Tellegen (1995/2003). Multidimensional Personality Questionnaire

[14] Cloninger, et al. (1994). Temperament and Character Inventory

[15] Peterson & Seligman (2004). Values in Action Character Survey

[16] Pozzebon, et al. (2010). Oregon Vocational Interest Scales

[17] Goldberg, L. R. (1990). An alternative “Description of personality”: The Big-Five factor structure

[18] Carver & White (1994). Behavioral Inhibition/Activation Systems

[19] DeYoung, C. G., Peterson, J. B., & Higgins, D. M. (2002). Higher-order factors of the Big Five predict conformity: Are there neuroses of health?

[21] Markey and Markey’s (2009)

[22] Goldberg, L. R. (1992). The development of markers for the Big-Five factor structure. Psychological Assessment, 4, 26-42

[23] David M. Condon, An empirically-derived, hierarchically-organized self-report personality assessment model

[24] William Moulton Marston (2008). Emotions of Normal People

curl -X GET "https://api.sentino.org/api/inventories"
-H "Authorization: Token sentino_api_token"
-H "Content-Type: application/json"

 {
    "inventories": [
        "6fpq",
        "8ics",
        "ab5c",
        "adj",
        "bfas",
        "big5",
        "big7",
        "bisbas",
        "cpi",
        "disc",        
        "emoint",
        "hexaco",
        "ipc",
        "jpi",
        "mpq",
        "neo",
        "orais",
        "orvis",
        "qb6",
        "riasec",        
        "spi",
        "tci",
        "via"
    ]
}

Inventory Items

This endpoint retrieves all the items for a given inventory. Ask people how these items relate to them and you will be able to get a highly confident psychological profile by scoring items.

Instead of <inventory> you should choose a particular inventory from the proposed list of personality inventories.

curl -X GET "https://api.sentino.org/api/items/neo"
-H "Authorization: Token sentino_api_token"
-H "Content-Type: application/json"

{
    "inventory": "neo",
    "items": [
        "I a lot in my spare time.",
        "I act comfortably with others.",
        "I act wild and crazy.",
        "I act without thinking.",
        "I adapt easily to new situations.",
        "I am a creature of habit.",
        "I am able to control my cravings.",
        "I am able to stand up for myself.",
        "I am afraid of many things."
         ...
    ]
}

Index Items

This endpoint retrieves all items for a given index of the inventory.

Instead of <inventory> you should choose a particular inventory from the list of the inventories.

Instead of <index> it is necessary to specify a particular index of the inventory. You can look through the list of available inventories at the address: https://api.sentino.org/api/inventories/<inventory> (please specify the previously chosen inventory).

curl -X GET "https://api.sentino.org/api/items/neo/anger"
-H "Authorization: Token sentino_api_token"
-H "Content-Type: application/json"

{
    "inventory": "neo",
    "index": "anger",
    "items": [
        "I am not easily annoyed.",
        "I am often in a bad mood.",
        "I get angry easily.",
        "I get irritated easily.",
        "I get upset easily.",
        "I keep my cool.",
        "I lose my temper.",
        "I rarely complain.",
        "I rarely get irritated.",
        "I seldom get mad."
    ]
}

Chatbot

Sentino chatbots are served as APIs and expect the token to be included in all requests to the server. Please refer to the Authentication section above to receive your own API token.

Create Link

In order to launch and further operate your tailor-made psychological chatbot you need to create the following elements:

• A unique link intended for management of all the subsequent operations, endpoints, and requests.
• A person (a virtual personality represented as a database) needed for data collection, processing, and updating.
• A bot (your psychological assistant) with all the relevant features designed for personality-related conversations with individuals.
• A chat (a separate conversation with a particular person) used for user engagement, as well as for data gathering and registration.

You can use four individual queries to create these elements. However, the easiest and the most convenient way to do this is described below. It allows using a single query to generate a link, a bot, a person, and a chat – all at a time.

First, you should specify all the chatbot parameters listed in the following table.

Then, you should also define the relevant personality parameters listed below:

The following input command returns four unique identification numbers: for the link (link_id), bot (bot_id), person (person_id), and chat (chat_id).

{"bot": {
        "name": "Demo HR Bot",
        "scenario": "psy",
        "tags": ["sentino"],
        "settings": {
            "inventories": ["big5","mbti"],
            "n_personality_questions": 2,
            "resume": "My name is Deniss. I am 35. I have graduated from...",
            "job_title": "Software Engineer",
            "job_description": "You must code very well",
            "company_title": "Sentino",
            "company_description": "Sentino is a SAAS service provider located at...",
            "questions": [
                "Do you easily make decisions that affect others?",
                "Do you like to be in charge?"]
                    },
        "messages": {
            "started": "Hi! Thank you for your time. I will be your interviewer for today. Let's start the interview.\n<q>What adjectives describe you best?</q>",
            "completed": "The interview has been completed. Thank you.",
            "show_result": "True"
                    }
        },
"person": {
        "inventories": ["big5","mbti"],
        "data": {
            "name": "Test",
            "email": "test@sentino.org"
                }
          }
}

{
    "link_id": "41d62ed5-f287-455f-9c50-207119253d47",
    "chat_id": "b8a01923-33a5-4d60-ad59-9eaa454cb466",
    "person_id": "22e1d5b2-fcad-4d58-9929-442258f1cb9c",
    "bot_id": "6ec793aa-be8f-4f2f-899c-48a559087cf6",
    "meta": {
        "link_url": "https://api.sentino.org/link/41d62ed5-f287-455f-9c50-207119253d47"
    },
    "bot": {
        "resume": "My name is Deniss. I am 35. I have graduated from...",
        "job_title": "Software Engineer",
        "questions": [
            "Do you easily make decisions that affect others?",
            "Do you like to be in charge?",
            "What adjectives best describe you?",
            "Do you prefer to work independently or in a team?"
        ],
        "inventories": [
            "big5",
            "mbti",
            "mbti-type"
        ],
        "company_title": "Sentino",
        "job_description": "You must code very well",
        "company_description": "Sentino is a SAAS service provider located at...",
        "n_personality_questions": 2
    }
}

Start Link

Once the previous step is completed, your chatbot is created and properly set. However, you need to activate it via the “Start Link” function.

curl -X PATCH "https://api.sentino.org/api/link/{link_id}/start"-H "Authorization: Token sentino_api_token"
-H "Content-Type: application/json"

{
    "success": true
}

After that the chatbot is ready for further operation.

Get Messages

While the conversation is in progress, at any convenient time, you can easily get all the chat messages at your own discretion. Please use the following query for this purpose.

curl -X GET "https://api.sentino.org/api/chat/{chat_id}"-H "Authorization: Token sentino_api_token"
-H "Content-Type: application/json"

{
    "chat_id": "0c24494c-bbe5-46b9-9df4-9421a9473f8e",
    "bot_id": "a3e42ec5-3b41-48d0-b6b2-8ef980fbee20",
    "person_id": "07c4c7af-4887-4feb-8db4-0a929c756f95",
    "data": {
        "messages": [
            {
                "role": "assistant",
                "text": "Hi! Thank you for your time. I will be your interviewer for today. Let's start the interview.\n<q>Do you easily make decisions that affect others?</q>",
                "time": 1710326274.13,
                "state": "started"
            }
        ]
    }
}

Reply

You should use the “POST” command to provide the answers to the questions asked by the chatbot. Among other data, this command returns the next question for the respondent to answer.

{

    "text": "I avoid decisions that affect others."
}

{
    "text": "I avoid decisions that affect others.",
    "reply": {
        "role": "assistant",
        "text": "Do you like to be in charge?",
        "finish_reason": "stop",
        "state": "ongoing"
    },
    "chat_id": "0c24494c-bbe5-46b9-9df4-9421a9473f8e",
    "bot_id": "a3e42ec5-3b41-48d0-b6b2-8ef980fbee20",
    "person_id": "07c4c7af-4887-4feb-8db4-0a929c756f95"
}

Complete Link

Once the conversation is finished, all the questions are asked and properly answered, the chat should be completed. Please use the following query in order to manually complete the chat.

curl -X PATCH "https://api.sentino.org/api/link/{link_id}/complete"-H "Authorization: Token sentino_api_token"
-H "Content-Type: application/json"

{
    "success": true
}

Otherwise, the bot can apply the auto-completion function:

curl -X GET "https://api.sentino.org/api/chat/{chat_id}"-H "Authorization: Token sentino_api_token"
-H "Content-Type: application/json"

{
    "chat_id": "0c24494c-bbe5-46b9-9df4-9421a9473f8e",
    "bot_id": "a3e42ec5-3b41-48d0-b6b2-8ef980fbee20",
    "person_id": "07c4c7af-4887-4feb-8db4-0a929c756f95",
    "data": {
        "items": [
            {
                "text": "I avoid decisions that affect others.",
                "context": "Do you easily make decisions that affect others?"
            },
...
            {
                "role": "assistant",
                "text": "<stop>\nThe interview has been completed.\nPlease reload the page to see the results.\n(normally it takes less than a minute for creating a report, keep reloading).",
                "time": 1710326715.042,
                "state": "completed"
             }
}

Get Report

Once the conversation is completed and all the relevant data is collected, it’s time to get a comprehensive psychological report. The query described below is specifically intended for this purpose. It returns the personality report in JSON format.

curl -X GET "https://api.sentino.org/api/link/{link_id}/report"
-H "Authorization: Token sentino_api_token"
-H "Content-Type: application/json"

{
    "info": {
        "big5": {
            "openness": {
                "i": 2,
                "label": "HIGH",
                "score": 1,
                "blocks": [
                    {
                        "rank": 0,
                        "text": "As an individual with a high score in openness, you are curious and imaginative, always eager to explore new ideas, cultures, and experiences. You have a deep passion for understanding the world, constantly seeking fresh insights and making connections. Your ability to think creatively allows you to tackle challenges in unique ways, coming up with innovative solutions. You often express your appreciation for aesthetics and beauty through art forms like music, literature, or painting. Your open-mindedness and intellectual flexibility make you a valuable asset to any team, bringing in new perspectives and ideas that challenge the usual norms.",
                        "title": "Summary"
                    }
                ],
                "quantile": 0.6666666666666666,
                "confidence": 0.1
            },
…
    "summary": {
        "mbti": "ENFJ",
        "qualities": [
            "creative",
            "optimistic",
            "helpful",
            "team player"
        ],
        "person_summary": "The interviewee is a creative, optimistic, and helpful individual who prefers working in a team.",
        "follow_up_questions": [
            "Can you share a specific example of a time when your creativity helped solve a problem?",
            "How do you approach helping others in a team setting?",
            "What motivates you to stay optimistic in challenging situations?"
        ]
    }
}

If the value “True” was assigned for the parameter “show_results” at the “Create Link” step, this report is also available in HTML format, which is the most suitable format while presenting the personality insights for the respondent. The command returns the HTML code that can be easily presented as a page.

curl -X GET "https://api.sentino.org/api/link/{link_id}"
-H "Authorization: Token sentino_api_token"
-H "Content-Type: application/json"

<!DOCTYPE html>
<html>
<head>
	<title>Sentino Testing</title>
	<meta charset="UTF-8">
	<meta name="viewport" content="width=device-width, initial-scale=1.0">
	<!-- Bootstrap CSS -->
	<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/4.5.2/css/bootstrap.min.css">

    <script src="https://ajax.googleapis.com/ajax/libs/angularjs/1.6.4/angular.min.js"></script>

...			  

</script>

</body>
</html>

Please note that an attempt to get a report while the conversation between the chatbot and the user is still in progress returns the following result:

curl -X GET "https://api.sentino.org/api/link/{link_id}/report"
-H "Authorization: Token sentino_api_token"
-H "Content-Type: application/json"

{
    "success": false,
    "message": "the interview is still ongoing"
}

Stop Link

If you have already collected all the necessary data and completed the chatbot operation, you need to deactivate the link. Please use the link_id and the following query.

curl -X PATCH "https://api.sentino.org/api/link/{link_id}/stop"
-H "Authorization: Token sentino_api_token"
-H "Content-Type: application/json"

{
    "success": true
}

Questionnaires

This endpoint lists all (20+) questionnaires available out-of-the-box. Please note that you can create a questionnaire of your own for any inventory (see the section create a questionnaire below).

curl -X GET "https://api.sentino.org/api/questionnaires"
-H "Authorization: Token sentino_api_token"
-H "Content-Type: application/json"

  {
    "questionnaires": [
        "neo.sentino.90",
        ...
    ]
  }

Questionnaire

Select a particular questionnaire to view its items and scorings.

Instead of <questionnaire> you should choose one questionnaire from the list of available questionnaires.

curl -X GET "https://api.sentino.org/api/questionnaire/neo.sentino.90"
-H "Authorization: Token sentino_api_token"
-H "Content-Type: application/json"

{
    "questionnaire": "neo.sentino.90",
    "items": [
        "I am open about my feelings.",
        "I crave the experience of great art.",
        ...
        ]
}

Create a Questionnaire

You can easily create a questionnaire of your own based on one or several pre-chosen personality inventories. Please provide n – a number of items you need. Instead of <inventories> you should specify particular inventories from the list of inventories. By default, Sentino API uses the highly-efficient “smart” method for item search and selection.

curl -X POST "https://api.sentino.org/api/questionnaire"
-H "Authorization: Token sentino_api_token"
-H "Content-Type: application/json"
-d '{
    "inventories": ["big5", "neo"],
    "method": "smart",
    "n": 30
    }'

{
    "inventories": [
        "big5",
        "neo"
    ],
    "method": "smart",
    "n": 30,
    "items": [
        "I respect authority.",
        "I dislike routine.",
        "I am hard to get to know.",
        "I get angry easily.",
        "I have a rich vocabulary.",
        "I am not highly motivated to succeed.",
        "I react slowly.",
        "I prefer variety to routine.",
        "I look down on others.",
        "I lose my temper.",
        "I get caught up in my problems.",
        "I do not like poetry.",
        "I take charge.",
        "I do crazy things.",
        "I express childlike joy.",
        "I contradict others.",
        "I often feel blue.",
        "I break rules.",
        "I seldom get emotional.",
        "I seek adventure.",
        "I am hard to get to know.",
        "I avoid crowds.",
        "I enjoy wild flights of fantasy.",
        "I often eat too much.",
        "I have a rich vocabulary.",
        "I tend to vote for liberal political candidates.",
        "I believe that I am better than others.",
        "I know how to get around the rules.",
        "I leave a mess in my room.",
        "I stumble over my words."
    ]
}

Item Analysis

Sentino API uses Natural Language Processing (NLP) algorithms to understand the written input of human language. To understand an item is to know how it relates to the known psychological inventories. This ensures that the resulting analysis is always based on the data of real people.

These endpoints will help you to get insights into the item itself, providing you with a multifaceted analysis. The main question is the following: what psychological traits are hidden behind an item?

Item classification

API strongly differentiates a psychologically meaningful information from the rest. This endpoint classifies the given item according to the following categories below. The result is a probability of belonging to a certain category with a range of [0, +1]). Probability higher than 0.5 is considered relevant.

Query Parameters

curl -X POST "https://api.sentino.org/api/item/classify" 
-H "Authorization: Token sentino_api_token"
-H "Content-Type: application/json" 
-d '{"text": "I am brave"}'

{
    "text": "I am brave",
    "lang": "en",
    "basics": {
        "is_psy": 0.927,
        "is_mood": 0.0,
        "is_item": 0.928,
        "valence": 0.581,
        "mean": 0.568,
        "proba": [0.14, 0.31, 0.55]
    },
    "topics": ["psy"],
    "proba": {
        "psy": 0.927,
        "food_preference": 0.003,
        "parental_status": 0.019,
        "age": 0.068,
        "gender": 0.129,
        "health_status": 0.014,
        "name": 0.069,
        "skill": 0.199,
        "appearance": 0.217,
        "location_origin": 0.015,
        "family_status": 0.0,
        "ethnicity": 0.017,
        "education_status": 0.011,
        "religion": 0.007,
        "language": 0.0,
        "location_residence": 0.0,
        "orientation": 0.0,
        "marital_status": 0.002,
        "sibling_status": 0.0
        ...
    }
 }

Item projection

The API allows analyzing a given self-statement (item) by projecting it onto specified personality inventory (projection correspondence range is [-1, +1]). You should choose a particular inventory from the list of personality inventories.

Keep in mind, it only makes sense for psychologically relevant statements.

This endpoint shows the projection of a given item onto a specified personality inventory.

curl -X POST "https://api.sentino.org/api/item/projection" 
-H "Authorization: Token sentino_api_token"
-H "Content-Type: application/json" 
-d '{"text": "I am brave", "inventories": ["big5"]}'

 {
    "text": "i am brave",
    "inventories": [
        "big5"
    ],
    "lang": "en",
    "projection": {
        "big5": {
            "agreeableness": -0.025,
            "conscientiousness": 0.051,
            "extraversion": 0.313,
            "neuroticism": -0.194,
            "openness": 0.293
        }
    },
    "basics": {
        "valence": 0.573,
        "is_item": 1.0,
        "is_psy": 1.0,
        "is_mood": 0.0,
        "proba": [
            0.166,
            0.057,
            0.777
        ],
        "mean": 0.611
    }
}

Errors

Sentino API uses the following error codes: