Sonality Logo
Page Content

Get Started

Welcome to the Sonality API! Our API allows you to integrate personality assessment functionalities seamlessly into your applications. With Sonality, you can dynamically create, manage, and retrieve assessments to gain valuable insights into individual personalities. This guide will help you get started quickly, providing you with the necessary steps to configure your environment and begin making API calls.

API Reference

API URL

https://sonality.runasp.net/

Create Assessment

Creates a single assessment in our system.
POST/api/assessments

Request Body

assessmentType
string, REQUIRED
The assessment type that you want to create.
Values:
- MyerBriggs - The Myer Briggs Type indicator Personality Test
- BigFive - The Big Five Model Personality Test
totalQuestions
int, REQUIRED
The number of questions you want returned for this assessment.
- Range: 30 - 100
subscriptionUri
string, OPTIONAL
The URL that you want the results sent to when the assessment is completed.
example Requestcurl -X 'POST' \
'https://{fqdn}/api/assessments' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
      "assessmentType": "myerbriggs",
      "totalQuestions": 50,
      "subscriptionUri": "https://mycallback.com/assessments"
}'

Response Body

assessmentId
string
The assessment id reference in our system that you will make subsequent requests with.
url
string
The url users can access to complete the assessment if you want to use our hosted page.
example Response - SUCCESS{
     "assessmentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
     "url": "https://sonalityui.runasp.net/?id=3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Retrieve Assessment

Gets the details of a previously created assessment, and the corresponding results if it was completed.
GET/api/assessments/{id}

Request Path Parameter

id
string, REQUIRED
The assessment id that you want to retrieve.
example Requestcurl -X 'GET' \
'https://{fqdn}/api/assessments/2f01cd54-6a11-494a-824e-4c8559c46a6d' \
-H 'accept: application/json'

Response Body

id
string
The assessment id reference in our system.
type
string
The assessment type name.
initiated
datetime
The date and time the assessment was created.
completed
datetime
The date and time the assessment was completed.
totalQuestions
int
The total number of questions requested.
status
string
The status of the assessment.
Values:
 - Inititated
 - Completed
personality
string
The personality type determined based on the assessment responses.
results
object
The list of individual trait results and their percentages. See Results object.
example Response - BEFORE ASSESSMENT COMPLETION{
    "id": "e794bf90-9e69-4832-9acc-297641207115",
    "type": "Myer-Briggs Type Indicator",
    "initiated": "2024-06-12T20:17:26.1747361",
    "totalQuestions": 40,
    "status": "Initiated"
}
example Response - After ASSESSMENT COMPLETION{
    "id": "e794bf90-9e69-4832-9acc-297641207115",
    "type": "Myer-Briggs Type Indicator",
    "initiated": "2024-06-12T20:17:26.1747361",
    "completed": "2024-06-12T20:44:07.6099232",
    "totalQuestions": 40,
    "status": "Completed",
    "personality": "ESTJ-A",
    "results": [
    {
      "traitGroup": "Introversion/Extraversion",
      "traits": [
       {
            "traitName": "Introversion",
            "percentage": 30,
            "acronym": "I"
      },
      {
         "traitName": "Extraversion",
         "percentage": 70,
         "acronym": "E"
       }
      ]
    },
    {...}
    {
       "traitGroup": "Assertive/Turbulent",
       "traits": [
        {
           "traitName": "Assertive",
           "percentage": 62,
           "acronym": "-A"
       },
       {
           "traitName": "Turbulent",
           "percentage": 38,
           "acronym": "-T"
        }
       ]
     }
   ]
}

Update Assessment

Allows you to submit the answers for a single assessment.
PATCH/api/assessments/{id}

Request Path Parameter

id
string, REQUIRED
The assessment id that you want to retrieve.

Request Body

answer
object, REQUIRED
The list of question and answer ids for the indicated assessment. See Answer object.
example Requestcurl -X 'PATCH' \
'https://{fdqn}/api/assessments/e794bf90-9e69-4832-9acc-297641207113' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '[
  {
    "answerId": 1,
    "questionId": 29
  },
  {
    "answerId": 2,
    "questionId": 4
  },
  {
    "answerId": 3,
    "questionId": 33
  },
  {
    "answerId": 1,
    "questionId": 89
  },
  {
    "answerId": 5,
    "questionId": 20
  }
]'

Response Body

example Response - SUCCESS{
}

Retrieve Assessment Questions

Gets the paginated and customized questions for a single assessment.
GET/api/questions

Request Query Parameters

assessmentId
string, REQUIRED
The assessment id that you want to retrieve the questions for.
pageNumber
int, OPTIONAL
The page number to retrieve for the current request.
Default Value: 1
pageSize
int, OPTIONAL
The total number of questions that should be returned for page.
Default Value: 10
example Requestcurl -X 'GET' \
'https://{fqdn}/api/questions?assessmentid=29ef4b9e-fda5-4ec9-8bae-c89a63b327aa&pagenumber=1&pagesize=5' \
-H 'accept: application/json'

Response Body

assessmentId
string
The assessment id.
questions
object
The paginated list of questions for the assessment. See Questions object.
pageNumber
int
The page number of the current request.
pageSize
int
The number of question returned for the current page.
totalCount
int
The total number of question that are available for request in this assessment.
hasNextPage
boolean
Indicates if there are more pages of questions available after the current page.
example Response - Success{
   "assessmentId": "29ef4b9e-fda5-4ec9-8bae-c89a63b327aa",
   "questions": {
     "items": [
      {
         "id": 32,
         "description": "I enjoy brainstorming and coming up with new ideas."
      },
      {
         "id": 73,
         "description": "Making decisions under pressure can be difficult."
      },
      {
         "id": 53,
         "description": "I often change plans at the last minute to take advantage of new opportunities."
      },
      {
         "id": 91,
         "description": "I consider how my actions will impact others before making a decision."
      },
      {
         "id": 99,
         "description": "I believe it's important to be compassionate and sensitive to others' feelings."
      }
   ],
   "pageNumber": 1,
   "pageSize": 5,
   "totalCount": 30,
   "hasNextPage": true
  }
}

Hosted Assessment Page

Page that allows users to view questions and submit responses for the specified assessment. Sonality will handle the retrieval of questions, display them to the user, update the assessment with the responses and then send the personality results to your subscription uri that was set up when creating the assessment. The uri to access this page will be returned in the Create Assessment response. You can allow users to browse to the page or embed it in your site as an iframe.

Request Query Parameters

id
REQUIRED
The assessment id that you want to retrieve the questions for.
pageNumber
int, OPTIONAL
The page number to retrieve for the current request.
Default Value: 1
pageSize
int, OPTIONAL
The total number of questions that should be returned for page.
Default Value: 10
example Requesthttps://sonalityui.runasp.net/?id=94994ef9-fd88-4dfe-8636-d35cdfd85c74&pagenumber=1&pagesize=10

Response Body

subscriptionId
integer
The ID of the subscription.
eventType
string
The type of event that triggered the callback.
Values:
 - AssessmentCompleted
 - AssessmentCreated
assessment
object
The details of the assessment with results.
example ResponseThe user will be shown the assessment results which will also be returned to the subscription uri setup when creating the assessment.
{
   "subscriptionId": 2,
   "eventType": "AssessmentCompleted",
   "assessment: {
       "id": "e794bf90-9e69-4832-9acc-297641207115",
       "type": "Myer-Briggs Type Indicator",
       "initiated": "2024-06-12T20:17:26.1747361",
       "completed": "2024-06-12T20:44:07.6099232",
       "totalQuestions": 40,
       "status": "Completed",
       "personality": "ESTJ-A",
       "results": [
       {
         "traitGroup": "Introversion/Extraversion",
         "traits": [
          {
            "traitName": "Introversion",
            "percentage": 30,
            "acronym": "I"
         },
         {
            "traitName": "Extraversion",
            "percentage": 70,
            "acronym": "E"
         }
        ]
       },
       {...}
       {
          "traitGroup": "Assertive/Turbulent",
          "traits": [
           {
              "traitName": "Assertive",
              "percentage": 62,
              "acronym": "-A"
          },
          {
              "traitName": "Turbulent",
              "percentage": 38,
              "acronym": "-T"
           }
          ]
        }
      ]
   }
}

Errors

All our endpoints return errors in the following format, along with the appropriate status code in the actual HTTP response.

Error Properties

type
string
The type/Name of error received.
Values:
 - Not Found
 - Bad Request
 - Internal Server Error
message
string
A more detailed description of the error.
statusCode
integer
The HTTP standard status code of the error.
extensions
object
May contain additional details about the error, normally when it is a bad request.
Error Response Model{
   "type": "string",
   "message": "string",
   "statusCode": 0,
   "extensions": {
      "additionalProp1": "string",
      "additionalProp2": "string"
   }
}

Models

Results object
  • TraitGroup
    string
    Represents the name of the trait group.
  • Traits
    List
    A list of objects representing individual traits and their details.
  • TraitName
    string
    The name of the trait.
  • Percentage
    double
    The percentage value representing the strength or presence of the trait.
  • Acronym
    string
    The acronym associated with the trait.
Answer object
  • answerId
    int
    The answer id that corresponds to different weightings based on the Likert scale.
    Values:
     - 1 - Strongly Disagree
     - 2 - Disagree
     - 3 - Neutral
     - 4 - Agree
     - 5 - Strongly Agree
  • questionId
    int
    Represents the id that references the question in our system, that will be resent in your Update request.
    Note: These will not be sent in incremental values because our assessments select random questions from the pool.
Questions object
  • items
    List
    A list of objects representing the assessment questions.
  • id
    int
    Represents the id that references the question in our system, that will be resent in your Update request.
    Note: These will not be sent in incremental values because our assessments select random questions from the pool.
  • description
    string
    The question that should be presented to the user.