Introduction

Welcome to Sentino API!

Sentino API is a data-driven, AI-powered service built to provide insights into one's personality.

Request API token and go directly to Use Cases to explore the most common scenarios.

All end-points of Sentino API are explained in details. Examples are provided - you can view code examples in the dark area to the right.

The key idea of Sentino API is to transform any type of information into psychologically meaningful representation. You will be able to transform or score text (and score facts) about a person into various scientifically proven inventories, such as Big 5, Neo and other. Also, you would be able to create a psychological profile of a person and continuously update it, by providing new information.

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 or try Self-statement analysis - a visual tool to explore item-related functionality.
• 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 facts. Facts can be extracted from questionnaires a person fills in, a person's self-description or in other form. See Scoring and Person for more details.

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

Authentication

To authorize, use this code:

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

Make sure to replace sentino_api_token with your API key.

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 by e-mail: info@sentino.org or through about us page. 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:

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 is important.

One of the easiest way to explore the API is to chat with SentinoBot. Sentino Bot is an AI-powered chatting bot was built that leverages a lot of API’s functionality. One can see Sentino API in action by chatting with the bot on the website sentino.org/bot or via Facebook Messenger facebook.com/sentinobot.

Use cases

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

Below we discuss two most common scenarios. 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 adding new information, check out the next use case: manage profile.

Big 5 traits from 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 from a questionnaire

Suppose, you asked a person well-posed questions and gathered the responses. In this case, you should use another endpoint: Score Facts, 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 Big5 and Neo

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

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

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

1. pick the inventories 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 facts

Manage 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 (facts) 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 "facts" about a person (like self-description or item-response pairs)
• get person profile for Big5, Neo, or other inventories (depending on your needs)
• add more facts 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 facts makes adding new information more price-efficient. You only pay (for commercial plan) for the newly added text.

When you delete a person, no personal information is being kept (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 want to track one person over long time, 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.

Score Text

Using this endpoint, one 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. Then every sentence is labeled with corresponding topic (see Item Classification) and inventory (like Big5, Neo etc., see Item inventories).

You can try Self-Description Analysis - a visual tool that gives a glimpse on this endpoint.

HTTP Request POST https://api.sentino.org/score

curl -X POST "https://api.sentino.org/score" 
-H "Authorization: Token sentino_api_token"
-H "Content-Type: application/json" 
-d '{
    "text": "I am 30 years old man. 
        I studied physics and currently work as a software engineer. 
        I am married and have a couple of kids. 
        What else I can tell... 
        I am open to new experience and like to chat. I am being nasty sometimes.",

    "inventories": ["big5"],

    "lang": "en"
    }'

The above command returns JSON structured like this:

{
    "text": "I am 30 years old man...",
    "inventories": ["big5"],
    "scoring": {
        "big5": {
            "openness": {
                "quantile": 1.0,
                "score": 1.0,
                "confidence": 0.134,
                "confidence_text": "low"
            }
            ...
        }
    },
    "lang": "en"
}

Score Facts

If you collected a well-structured item-response pairs, this endpoint is for you. Provide the facts and get the psychological representation of a person.

HTTP Request POST https://api.sentino.org/score/facts

Facts

curl -X POST "https://api.sentino.org/score/facts" 
-H "Authorization: Token sentino_api_token"
-H "Content-Type: application/json" 
-d '{
  "inventories": ["big5"],
  "facts": [
    {
      "text": "My name is John. I am an extravert.",
      "lang": "en"
    },
    {
      "text": "I do not like to chat.",
      "response": "disagree"
    }
  ]
}'

The above command returns JSON structured like this:

{
    "facts": [...],
    "inventories": ["big5"],
    "scoring": {
        "big5": {
            "extraversion": {
                "quantile": 1.0,
                "score": 1.0,
                "confidence": 0.194,
                "confidence_text": "low"
            }
            ...
        }
    },
    "lang": "en"
}

Fact is a piece of information about a person. There are two types of facts currently supported:

See some examples on the right.

Responses

There are many ways to response to a question or psychological item. However, internally all responses are translated into the seven distinct groups: from "strongly disagree" through "neutral" to "strongly agree". The table below shows typical synonyms to the core responses.

Soon to come: Time Stamp

For each fact a timestamp can be specified. This is required for example to account for time persistency of a fact. For example, “I am in a bad mood now” is usually constrained in time unlike “I am usually in a bad mood”. If a timestamp is not provided, it is set to the current time.

Person

Here you find all endpoints for managing psychological profiles. The advantage of using these endpoints is the ability to continuously add a new information about the person and retrieve automatically updated profile.

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

Create a person

To create a person, do the query below.

A person ID will be returned. All other person-related endpoints depend on this ID. At this point no charges (even for commercial users) has been applied.

HTTP Request POST https://api.sentino.org/person/create

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

The above command returns JSON structured like this:

{
  "id": "dfefFdfewdfXDDf"
}

Add facts

To add facts, do the query below.

Use the person to refer to relevant person. Provide as many facts as you want. Once the facts are provided, the scoring will take place for a chosen inventory. At this time, the charges apply (for commercial users) that depend on the length of the "text" field.

One can subsequently add "facts". Charges apply only to the newly added facts.

HTTP Request POST https://api.sentino.org/person/<id>/fact

curl -X POST "https://api.sentino.org/person/<id>/fact"
-H "Authorization: Token sentino_api_token"
-H "Content-Type: application/json"
-d '{
  "facts": [
    {
      "text": "My name is John. I am an extravert.",
      "lang": "en"
    },
    {
      "text": "I do not like to chat.",
      "response": "disagree",
      "lang": "en"
    }
  ]
}'

The above command returns JSON structured like this:

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

Person profile

This endpoint allows building a personal profile of out the facts.

To get a person profile (big5, neo, etc.) simply use the following query.

Note, if no relevant facts are provided you still get a default scoring (that depends on inventory). No charges are applied at this point as all scoring was performed during the fact adding step.

HTTP Request GET https://api.sentino.org/person/<id>/profile

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

The above command returns JSON structured like this:

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

Delete a person

To delete a person run the query below. The following will happen:

• person is deleted (id will not work anymore)
• all facts and performed scoring will be deleted
• information of the fact that scoring took place with the price will be kept (!)
• information of the query itself with the first 10 symbols (and length) of the facts will be kept (for debugging purposes)

HTTP Request DELETE https://api.sentino.org/person/<id>

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

The above command returns JSON structured like this:

{
  "message": "success"
}

Inventories

Inventory is basically a set of items that intend to measure 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 a well-established, proven to work in scientific literature questionnaires for understanding people's psyche.

These inventories can be used out of the box. If you need another inventory, please contact us.

Inventories

curl "https://api.sentino.org/inventories"
  -H "Authorization: Token sentino_api_token"

The above command returns JSON structured like this:

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

This endpoint shows all available personality inventories.

HTTP Request GET https://api.sentino.org/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

[6] Jackson, Paunonen, and Tremblay (2000). Six Factor Personality Questionnaire

[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?

[20] Jackson, Paunonen, and Tremblay (2000). Six Factor Personality Questionnaire

[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

Inventory Items

curl "https://api.sentino.org/items/neo"
  -H "Authorization: Token sentino_api_token"

The above command returns JSON structured like this:

{
    "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."
         ...
    ]
}

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 facts.

HTTP Request GET https://api.sentino.org/items/<inventory>

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

Index Items

curl "https://api.sentino.org/items/neo/anger"
  -H "Authorization: Token sentino_api_token"

The above command returns JSON structured like this:

{
    "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."
    ]
}

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

HTTP Request GET https://api.sentino.org/items/<inventory>/<index>

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

Instead of you should choose a particular index of the inventory. You can see them at https://api.sentino.org/inventories/<inventory> (mention the previously chosen inventory).

Questionnaires

This endpoint lists all questionnaires available out-of-the-box. Remember, you can create your own questionnaire for any inventory create a questionnaire.

curl "https://api.sentino.org/questionnaires"
  -H "Authorization: Token sentino_api_token"

The above command returns JSON structured like this:

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

HTTP Request GET https://api.sentino.org/questionnaires

Questionnaires

HTTP Request GET https://api.sentino.org/questionnaire/<questionnaire>

Select a particular questionnaire to view its items and scorings.

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

curl "https://api.sentino.org/questionnaire/neo.sentino.90"
  -H "Authorization: Token sentino_api_token"

The above command returns JSON structured like this:

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

Create a Questionnaire

Create a questionnaire to score a given inventory. Provide n - number of items you need and method for selecting items.

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

HTTP Request POST https://api.sentino.org/inventory/<inventory>/questionnaire/create

curl -X POST "https://api.sentino.org/inventory/neo/questionnaire/create" 
-H "Authorization: Token sentino_api_token"
-H "Content-Type: application/json" 
-d '{"n": 90, "method": "sentino"}'

The above command returns JSON structured like this:

{
    "inventory": "neo",
    "method": "sentino",
    "n": 90,
    "items": [
        ...
        "I do crazy things.",
        "I do not like the idea of change.",
        ...
        ]
}

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 getting insights into the item itself, providing you with a multifaceted analysis. The main question is the following: what psychological traits hides behind an item? Try out a Self-statement Analysis Tool that demonstrates item-level functionality.

Item classification

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

The above command returns JSON structured like this:

{
    "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
        ...
    }
 }

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.

HTTP Request POST https://api.sentino.org/item/classify

Query Parameters

Item projection

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

The above command returns JSON structured like this:

 {
    "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
    }
}

The API allows to analyze a given self-statement (item) by projecting it on a 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.

HTTP Request POST https://api.sentino.org/item/projection

Errors

The Sentino API uses the following error codes: