How do I use the Crystal API? (Closed Beta)

Explore the functions of the Crystal API below (closed beta).

The Crystal API is currently in closed beta.

Table of Contents

Overview

The Crystal API is currently available in beta. 

Activate your Token

We are not currently offering API tokens because the API is in closed beta.

Getting Started

Every request requires this header:

Authorization: Bearer YOUR_TOKEN

Assessments API

The Assessments API enables you to embed a white-labeled DISC personality test into your app, have your users complete the test and then get personality data results returned as a JSON object that you can store and display on your page. 

1. Embed the DISC Assessment

Add this code to your website to embed the DISC assessment

<link rel="stylesheet" type="text/css" href="https://cdn2.hubspot.net/hubfs/1716276/embeddable_assessments/disc/disc_assessment_v1.3.6.css" />
<div id="disc_assessment_root" data-api-token=TOKEN_HERE></div>
<script src="https://cdn2.hubspot.net/hubfs/1716276/embeddable_assessments/disc/disc_assessment_v1.3.6.js" />

By default, the Assessments API returns the default content objects that are available on the Crystal website as if a user signed up and took the personality test (see example response below). If you want to access full, unlocked profile content, you'll need to purchase credits through the dashboard by visiting this link: https://www.crystalknows.com/app/team-assessments

To use profile credits, add an attribute to the <div> as follows:

data-use-credit

<div id="disc_assessment_root" data-api-token=TOKEN_HERE data-use-credit></div>

Unlocked content includes the following additional sections, which you can see an example of in this profile.

communication
meeting
emailing
selling
negotiation
feedback
conflict
change
strength
blind_spot
working_together

2. Handle the JSON Response

When a user submits their assessment, our API will handle calculating their DISC type and sending back a JSON response. To get that response, you will need to add a callback function to the global space.

<script>
  window.crystalKnowsDISCResponse = function (response) {
    console.log('Here is the personality JSON response:', response)
  }
</script>

Response:

Content-Type: application/json

{
"personalities": {
"disc_type": "Id"
},
"images": {
"disc_map": "https://auth-api.crystalknows.com/images/disc_map/4.png"
},
"content": {
"profile": {
"qualities": [
"Adventurous",
"Casual",
"Visionary",
"Enthusiastic",
"Spontaneous"
]
},
"behavior": {
"phrases": [
"Get bored easily",
"Make decisions quickly with gut instinct",
"Stick to the big picture",
"Say something sarcastic",
"Lead the conversation in a meeting"
]
},
"motivations": {
"phrases": [
"Exploration \u0026 discovery",
"Public speaking",
"Storytelling",
"Experiencing new things",
"Fun \u0026 excitement"
]
},
"drains": {
"qualities": [
"Using too much caution",
"Repetitive, routine tasks",
"Feeling micromanaged",
"Following lots of rules",
"Feeling stuck in the same place"
]
}
}
}

 

Status codes

  • Success: 200 status code
  • Unauthorized: 401 status code
  • Product needed: 402 status code

Analysis API

The Analysis API enables you to predict someone's personality from a text sample or PDF resume.

API Info

URL: 

https://api.crystalknows.com

POST /v1/analysis/pdf

Pass a PDF file in the body and it will return an ID that you can poll to see when it’s done analyzing your file.

Body:

{

  file: FILE.pdf  

}

Response:

{

  data: {

    id: string

  }

}

POST/v1/analysis/text

Pass an unstructured text sample of at least 60 words in the body.

Body:

{

 text: string,
first_name: string (optional),
last_name: string (optional),
email: string (optional) 

}

Response:

{
“data”: {
“personality”: {
“disc_type”: “IS”
},
“images”: {
“disc_map”: <URL>
},
“content”: {
“behavior”: [
“Find ways around the rules”,
“Feel comfortable as the primary speaker in a group”,
“Elevate new ideas”,
“Speak persuasively in a one-on-one meeting”,
“Take big risks”
],
“motivations”: [
“Opportunities to advance”,
“Winning other people over”,
“Ambitious goals”,
“Opportunities to perform and entertain”,
“Challenges”
],
“drains”: [
“Feeling held back by process”,
“Over-planning”,
“Repetitive, routine tasks”,
“Using too much caution”,
“Following lots of rules”
]
}
}

 

People API

The People API enables you to access all of the personality profiles associated with anyone on your Crystal team. This includes predicted profiles (e.g. people your team looked up using the Crystal Chrome Extension) and verified profiles (e.g. anyone who your team invited to take the personality test). Team administrators can use this data to create integrations to your own internal database or CRM.

GET /v1/people

Query Parameters:

query: string - filters people by name or email address

Response:

{
“data”: [
{
“first_name”: “John”,
“last_name”: “Smith”,
“photo_url”: “photo.png”,
“personality”: {
“disc_type”: “IS”,
“enneagram_type”: “1",
“myers_briggs_type”: “INFP”
},
“content”: {
“behavior”: [
“Find ways around the rules”,
“Feel comfortable as the primary speaker in a group”,
“Elevate new ideas”,
“Speak persuasively in a one-on-one meeting”,
“Take big risks”
],
“motivations”: [
“Opportunities to advance”,
“Winning other people over”,
“Ambitious goals”,
“Opportunities to perform and entertain”,
“Challenges”
],
“drains”: [
“Feeling held back by process”,
“Over-planning”,
“Repetitive, routine tasks”,
“Using too much caution”,
“Following lots of rules”
]
}
],
“total_pages”: 1,
“total_count”: 1
}

Unlocked Content

By default, the People API returns the default content objects that are available on the Crystal website as if a user signed up and took the personality test. If you want to access full, unlocked profile, you'll need to purchase credits through the dashboard by going to this link: https://www.crystalknows.com/app/team-assessments

To use profile credits, pass the `use_credit` query parameter. For example:

https://api.crystalknows.com/v1/people?use_credit=true

Unlocked content includes:

communication
meeting
emailing
selling
negotiation
feedback
conflict
change
strength
blind_spot
working_together