How do I use the Crystal API?

Explore the functions of the Crystal API below.

Activate your Token

Get your token and 30 free calls by visiting app.crystalknows.com/developers. On that page, you'll be able to access your token, and track how many calls you have remaining.

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.1.0.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.1.0.js" />

 

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"
]
},
"communication": {
"phrases": [
"Project enthusiasm and energy",
"Use visual aids when possible",
"Switch up the subject to keep things interesting",
"Tell a few jokes",
"Listen to and engage with his personal stories"
]
},
"meeting": {
"phrases": [
"Show excitement for new ideas",
"Expect them to be a couple of minutes late",
"Encourage them to share their thoughts",
"Use whiteboards and/or visual aids when possible",
"Send a reminder the day before"
]
}
}
}

 

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, PDF resume or LinkedIn profile URL.

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  

}

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”
],
“communication”: [
“Keep conversation brief”,
“Bring lots of energy to the conversation”,
“Project boldness and confidence (even at the risk of sounding impolite)“,
“Let him take the lead”,
“Stick to the big picture”
],
“meeting”: [
“Send a bulleted list with anything they need to prepare”,
“Avoid too much formality”,
“Prepare to be challenged”,
“Start by casting an exciting vision”,
“Make the meeting as short as possible”
]
}
}

POST /v1/analysis/linkedin

Pass a public LinkedIn URL.

Body:

{

  linkedin_url: string  

}

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”
],
“communication”: [
“Keep conversation brief”,
“Bring lots of energy to the conversation”,
“Project boldness and confidence (even at the risk of sounding impolite)“,
“Let him take the lead”,
“Stick to the big picture”
],
“meeting”: [
“Send a bulleted list with anything they need to prepare”,
“Avoid too much formality”,
“Prepare to be challenged”,
“Start by casting an exciting vision”,
“Make the meeting as short as possible”
]
}
}

POST /v1/analysis/linkedin/batch

Pass a CSV 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.csv  

}

Response:

{

  data: {

    id: string

  }

}

GET /v1/analysis/:ID

Pass the ID returned from these routes:

  • POST /v1/analysis/pdf
    • Returns a JSON object with the typical API response for a person
  • POST /v1/analysis/linkedin/batch
    • Returns a JSON object with a link to a CSV file containing the batched results. CSV file contains the URL in the first column and data in the second column.

This will return the results once we’ve finished analyzing your file.

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”
],
“communication”: [
“Keep conversation brief”,
“Bring lots of energy to the conversation”,
“Project boldness and confidence (even at the risk of sounding impolite)“,
“Let him take the lead”,
“Stick to the big picture”
],
“meeting”: [
“Send a bulleted list with anything they need to prepare”,
“Avoid too much formality”,
“Prepare to be challenged”,
“Start by casting an exciting vision”,
“Make the meeting as short as possible”
]
}
],
“total_pages”: 1,
“total_count”: 1
}

CURL Example

Getting a prediction from a LinkedIn URL:

curl --request POST \
--url https://api.crystalknows.com/v1/analysis/linkedin \
--header 'Authorization: Bearer <TOKEN>' \
--header 'content-type: multipart/form-data' \
--form linkedin_url=<LINKEDIN_URL>