How do I use the Crystal API for Personality Assessments?

Follow the steps outlined below to connect your site with Crystal API for Personality Assessments.

1. Get a Token

Any Crystal user can get a token to use the Crystal API for Personality Assessments. To get a token, visit this page in the Crystal dashboard.

We currently offer 5000 free calls per month and a rate limit of 500 calls per minute.

2. Add the "Take Personality Test" button to your app

On the Crystal API - Personality Assessments page, you can copy the example html that includes the button and your unique URL. The api_user_email parameter is optional but we recommend using it to ensure that you will be able to properly associate a user from your app with their Crystal profile. Setting the email parameter ensures that the user's crystal account will be set up with the email you specify which means you will be able to query for it later. If you do use the email parameter, be sure to URL encode the email so it can be properly parsed.

3. Implement the Crystal API


GET /v1/personality_assessments/find

Query parameters:

token:string (required) - Your api token
email:string (required)  - Email of user you are looking for
options[hiring]:boolean (optional) - Returns available hiring data

When querying for profiles, be sure to URL encode the email parameter.


Content-Type: application/json

"first_name": "Bob",
"last_name": "Smith",
"photo_url": https://photo_url.jpeg,
"personalities": {
"disc_type": "Di",
"enneagram_type": 5,
"myers_briggs_type": "INTP"
"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",
"drains": [
"Feeling held back by process",
"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"
"url": "",
"role": "Director"


Status codes

  • Success: 200 status code
  • Not found: 404 status code
  • Unauthorized: 401 status code