NAV Navbar
Logo
shell ruby javascript

API Reference

Welcome to the Crystal Connect API! This API provides access to our Global Personality Database and our Personality Analysis Engine.

API Summary

Global Personality Database

Our global personality database combines public data sources and manually submitted information to build accurate personality profiles for millions of people. Through our APIs, you can utilize the database we’ve accumulated over the years to enrich your profile data with personality attributes and present your users with tips on how to best communicate with their peers, coworkers, customers, and anyone else they interact with.

Personality Analysis Engine

Our API also lets your applications directly use text analysis engine to generate personality profiles. We’ve trained our machine learning algorithms so that, when fed a text sample, the algorithms can instantly produce a personality profile of the author. This allows your application to determine personality traits even when personally identifiable information is not present.

Client SDKs

The easiest and most efficient way to access our API is to use one of our SDKs:

Get Access

Contact us to request an Organization Access Token to start utilizing the API:

Contact the Crystal Team

API Endpoints

Here’s a quick overview of our API endpoints:

Method Endpoint Usage
POST /v1/profiles Request a profile (recommended)
POST /v1/profiles/async Request a profile (async)
GET /v1/profiles/results/:request_id Retrieve status for an (async) profile request

Authentication

In order to communicate with our API, you must send the following headers with every request:

Header Name Value
X-Org-Token The Organization Access Token provided to you by the Crystal Team.
curl -X "POST" "https://connect.crystalknows.com/v1/.../" \
     -H "X-Org-Token: $YOUR_ORG_TOKEN"
CrystalSDK.key = 'YOUR_ORG_TOKEN'
CrystalSDK.key = 'YOUR_ORG_TOKEN'

Profile

The Profile endpoint returns a personality profile based on the search criteria.

If you have an email, resume, bio, or another text sample written by the person you are searching for, you can include it in your request as a text_sample, along with a text_type.

We will use our Personality Analysis Engine to more accurately enrich the personality data returned from the endpoint. Sending a text sample will significantly increase match rates and accuracy.

Summary

Example Request

curl -X "POST" "https://connect.crystalknows.com/v1/profiles" \
     -H "X-Org-Token: $YOUR_ORG_TOKEN" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d $'{
  "first_name": "Drew",
  "last_name": "D\'Agostino",
  "email": "hello@crystalknows.com",
  "company_name": "Crystal",
  "location": "Nashville, TN",
  "text_type": "various",
  "text_sample": "I, Drew, Founder of Crystal, think that..."
}'
begin
  profile = CrystalSDK::Profile.search({
    first_name: "Drew",
    last_name: "D'Agostino",
    email: "drew@crystalknows.com",
    company_name: "Crystal",
    location: "Nashville, TN",
    text_sample: "I, Drew, the founder of Crystal, think that ...",
    text_type: "various"
  })

  print "Profile found!"
  print "First Name: #{profile.info.first_name}"
  print "Last Name: #{profile.info.last_name}"
  print "Predicted DISC Type: #{profile.info.disc_scores.type}"
  print "Prediction Confidence: #{profile.info.disc_scores.confidence}"
  print "DISC Image: #{profile.info.disc_image}"

  print "Personality Overview: #{profile.recommendations.overview}"
  print "Personality Qualities: #{profile.recommendations.qualities}"

  print "Likely motivations: #{profile.recommendations.motivations}"
  print "Likely behaviors: #{profile.recommendations.behavior}"

  print "Tips on emailing: #{profile.recommendations.emailing}"
  print "Tips on communication: #{profile.recommendations.communication}"
  print "Tips on building trust: #{profile.recommendations.building_trust}"
  print "Tips on selling: #{profile.recommendations.selling}"
  print "Tips on working together: #{profile.recommendations.working_together}"

rescue CrystalSDK::Profile::NotFoundError
  print "No profile was found"

rescue CrystalSDK::Profile::NotFoundYetError => e
  print "Profile search exceeded time limit: #{e.request.id}"

rescue CrystalSDK::Profile::RateLimitHitError
  print "The organization's API rate limit was hit"

rescue CrystalSDK::Profile::NotAuthedError => e
  print "Org token was invalid: #{e.token}"

rescue StandardError => e
  print "Unexpected error occurred: #{e}"

end
CrystalSDK.Profile.search({
  first_name: "Drew",
  last_name: "D'Agostino",
  email: "drew@crystalknows.com",
  location: "Nashville, TN",
  company_name: "Crystal",
  text_sample: "I, Drew, the founder of Crystal, think that ...",
  text_type: "various"
})
  .then((profile) => {
    console.log("Profile found!")
    console.log("First Name:", profile.info.first_name)
    console.log("Last Name:", profile.info.last_name)
    console.log("Predicted DISC Type:", profile.info.disc_scores.type)
    console.log("Prediction Confidence:", profile.info.disc_scores.confidence)
    console.log("DISC Image:", profile.info.disc_image)

    console.log("Personality Overview:", profile.recommendations.overview)
    console.log("Personality Qualities:", profile.recommendations.qualities)

    console.log("Likely motivations:", profile.recommendations.motivations)
    console.log("Likely behaviors:", profile.recommendations.behavior)

    console.log("Tips on emailing:", profile.recommendations.emailing)
    console.log("Tips on communication:", profile.recommendations.communication)
    console.log("Tips on building trust:", profile.recommendations.building_trust)
    console.log("Tips on selling:", profile.recommendations.selling)
    console.log("Tips on working together:", profile.recommendations.working_together)

  })
  .catch(CrystalSDK.Profile.NotFoundYetError, (err) => {
    console.log("Profile was not found in time limit: ", err.request.id)

  })
  .catch(CrystalSDK.Profile.NotFoundError, (err) => {
    console.log("Profile was not found")

  })
  .catch(CrystalSDK.Profile.NotAuthedError, (err) => {
    console.log("The organization token is not valid:", err.token)

  })
  .catch((err) => {
    console.log("Unexpected Error:", err)

  })

Method: POST

Endpoint: /v1/profiles

Usage: Returns a personality profile based on the search criteria

Request Type: application/json

Response Type: application/json

Request Format

Example Request Data

{
  "first_name": "Michael",
  "last_name": "Scott",
  "email": "michaelscott@dundermifflin.com",
  "company_name": "Dunder Mifflin",
  "location": "Scranton, PA",
  "text_sample": "Hey there, Jim! \nJust emailing to invite you and Pam to have dinner with Jan and I tonight!",
  "text_type": "email"
}
Param Type Description
first_name string First name of the person
last_name string Last name of the person
email string Email address of the person
company_name string Name of the company where the person works
location string Location of person. Formatting is ideally
city, state,
such as Nashville, TN.
text_sample string A paragraph (or more) of text written by the person.
text_type string The origin of the text given in the text_sample. This can be one of:
["email", "various", "bio", "resume"]
  1. first_name and last_name

  2. email

  3. text_sample and text_type

Response Format

Example Response Data

{
  "info": {
    "first_name": "Drew",
    "last_name": "D'Agostino",
    "disc_scores": {
      "type": "Ids",
      "confidence": 90
    },
    "disc_image": "https:\/\/www.crystalknows.com\/images\/learn\/disc\/ids_full.png"
  },
  "recommendations": {
    "emailing": {
      "overview": "This person is a gifted communicator who prioritizes relationships, and providing them with a new idea and a time\/place to follow up to discuss verbally will probably result in a fast response.",
      "phrases": [
        "Write with short casual language and abbreviations",
        "Don't take yourself too seriously",
        "Use emotionally expressive language",
        "Appeal to their feelings to drive them to action",
        "Use an emoticon :)"
      ]
    },
    "motivations": {
      "overview": "This person is <b>outgoing<\/b>, <b>optimistic<\/b>, and will encourage their colleagues to work hard, play hard. They thrives in workplaces that encourage <b>creativity<\/b>.",
      "phrases": [
        "New relationships",
        "Peer recognition",
        "Fun & excitement",
        "Feeling accepted",
        "Ambitious goals"
      ]
    },
    "communication": {
      "overview": "This person will appreciate a break in <b>momentum<\/b> to joke around and tell stories while getting to know their colleagues on a more personal level.",
      "phrases": [
        "Emphasize the future",
        "Use self-deprecating humor (don't act like you take yourself too seriously)",
        "Leave a conversation open-ended",
        "Tell a few jokes",
        "Exaggerate about any facts (not even a little bit)"
      ]
    },
    "behavior": {
      "overview": "This person will easily <b>build rapport<\/b> with those surrounding them. <b>Friendly<\/b>, <b>optimistic<\/b> and <b>eager<\/b>, their enthusiasm is contagious.",
      "phrases": [
        "Make a quick purchase decision",
        "Immediately feel comfortable speaking to a new person",
        "Focus on deep & close relationships rather than high quantity",
        "Make a decision more quickly than most people",
        "Forget something important"
      ]
    },
    "building_trust": {
      "overview": "This person might get bored by monotony, structure, and formality. Has a preference for <b>brainstorming<\/b>, often thinks out loud, and will look for feedback from their peers.",
      "phrases": [
        "Introduce them to others in your network",
        "Smile and make eye contact frequently",
        "Remember and ask about their personal details",
        "Challenge them on occasion",
        "Share your feelings frequently"
      ]
    },
    "selling": {
      "overview": "This person is decisive, energized by ideas, and overlooks details, so stick to the big picture and get to your point quickly. ",
      "phrases": [
        "Focus on the future plans for your product",
        "Try to schedule a meeting with other coworkers",
        "Use hyperbole to make a point (\"This is the best product in the world!\")",
        "Tell a past customer story instead of listing features",
        "Tell a story about the company instead of listing facts"
      ]
    },
    "working_together": {
      "overview": "This person is creative, decisive, a bit disorganized, overlooks details, and enjoys working with people.",
      "phrases": [
        "Confront conflict in person rather than via email",
        "Recognize their achievements verbally",
        "Express criticism in person or on the phone",
        "Express criticism via email",
        "Use purely logical appeals if you argue"
      ]
    },
    "overview": "This person is a gifted communicator, prioritizes relationships, and sometimes makes decisions based solely on instinct.",
    "qualities": [
      "Enterprising",
      "Influential",
      "Assertive",
      "Daring",
      "Charming"
    ]
  }
}

Listed below are the properties of a successful search response:

Param Type Description
info string General information about the profile
- first_name string First name on the profile (not always present)
- last_name string Last name on the profile (not always present)
- disc_scores string Contains all of the information regarding the person’s DISC analysis.
- - type string The (text) DISC type of the person.
- - confidence string An integer between 0-100. How confident our algorithms are in the analysis.
- disc_image string A URL of an image that can be displayed to represent the DISC Type
recommendations string All of Crystal’s recommendations for interacting with this person
- overview string Short summary of the personality profile
- qualities array An array of one-word personality traits associated with the profile
- emailing object Contains an overview of how this person reads and interprets emails and provides tips for writing a good email to them.
- - overview string This section provides the information your users need to ensure communication sent via email is written to the preferences of the personality the user is reaching out to. Crystal provides advice for outreach via email to the 4 main DISC personality types and 12 subtypes in order to produce a better response rate. Crystal calls this the “Return on Empathy” and it is proven to develop rapport faster and increase the success of recruiters, sales team, and anyone whose job involves lots of email outreach in their daily work flow.
- - phrases array Your users will be provided with short, punchy information about the personality of the recipient of the email correspondence they are constructing. These phrases are easy to read and can be scanned quickly when used in real-time. Phrase advice can also be used when communication on the phone.
- communication object Contains an overview of how this person communicates and tips on how to best communicate with them.
- - overview string Diction and choice of words is important to improving communication between your users and the people they are interacting with daily. The speaking overviews provide the preferences for reaching out to- and further understanding with the 4 main personality types and 12 subtypes of the DISC personality framework.
- - phrases array The phrases that populate beneath the Communication overviews inform the preferences for communication with the person your user is looking up or interacting with. These short statements provide advice and coaching for better communication in an easy-to-read format.
- motivations object Contains an overview of what motivates this person and a quick breakdown of these motivations.
- - overview string Understanding what motivates the behavior of the 4 main DISC personality types and 12 subtypes informs our behavior and communication preferences. Crystal provides your users with an understanding of these qualities in order to inform all daily interactions with the people that surround them. Understanding what motivates a personality increases the interactions when giving instructions, feedback, praise, and during conflict.
- - phrases array The phrases provided within the Motivations section gives your users shorthand understanding of the primary motivations of the people they are corresponding with. These phrases are written for easy understanding, quick reading and can be very helpful during phone calls.
- behavior object Contains information about how this person behaves in a normal situation and tips on their comfort zone.
- - overview string Each of the 4 main DISC personality types and 12 subtypes embody distinct behaviors. Your users will learn about what behaviors are attributed to the personality they are looking up or interacting with in order to cater to their own behavior to that person’s behavioral preferences.
- - phrases array These short statements provide your users with easy-to-read bullet points that provide a good synopsis of the natural behaviors exhibited by the personality of the person who they are interacting with. These phrases are especially helpful with people you don’t know and during phone calls when there is less time to prepare your talking points.
- building_trust object Contains an overview of how this person builds trust and some tips in building trust.
- - overview string The ability to build trust is crucial to growing relationships and this section provide a user with the information they need in order to build rapport more quickly with each of the 4 main DISC personality types and 12 subtypes. The DISC personality framework is built on supporting each personality’s best qualities and learning how to build trust will inform the support necessary for a user to work to the best of their capabilities.
- - phrases array Building trust is considered one of the most challenging learned behaviors and therefore, Crystal has developed short phrases to help coach your users toward better understanding of the people they interact with. These phrases are provided in easy-to-read bullet points for in order to break down the best way to build trust in an easy-to-read format.
- selling object Contains an overview of how to sell to this personality type and some quick tips.
- - overview string Each of the 4 main DISC types and 12 subtypes have distinct behaviors and communication styles that make up their preferred methods when engaging in a sale. The information provided in this section is especially helpful for recruiters, account managers, executives, and members of a sales team.
- - phrases array The bullet points provided in the Selling phrases portion break down the preferred behaviors and give advice on how to start the sales cycle to the personality a user interacts with. The advice in this section also helps inform the interaction and follow-up behavior or correspondence.
- working_together object Contains an overview of the person’s workplace habits and short tips on how to communicate in the workplace.
- - overview string This section takes all of the information and advice provided by Crystal in order to develop an infrastructure for developing a trusting relationship between two different personalities. This information is applicable to anyone within an office and helps navigate conflict, rapport, communication and general daily interactions.
- - phrases array These short statements provide a brief, easy-to-read understanding of how the two personalities selected will interact and how to enhance the relationship between these two people.
id string The Profile Request ID from the API.

HTTP Status Codes

Listed below are the HTTP Status Codes that might be sent with a response:

Code Title Meaning
200 OK Not an error - just happy things!
202 Not Found Yet Not found before time limit (request_id in response)
404 Not Found No profile was found
401 Unauthorized Organization Token was invalid
429 Rate Limit Hit You’ve hit the rate limit for your plan
500 Unexpected Error An unexpected error occurred

Try It Out

Try what you’ve learned against the live API!

To better understand the inputs, read the request format section.

...

...

Profile (Async)

When requesting large lists of profiles, or when wanting to have more fine-grained control over performance, we recommend using our asynchronous flow.

This flow allows us to process your requests in parallel and get the information back to you more quickly.

Summary

Example Request

curl -X "POST" "https://connect.crystalknows.com/v1/profiles/async" \
     -H "X-Org-Token: $YOUR_ORG_TOKEN" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d $'{
  "first_name": "Cory",
  "last_name": "Finger",
  "email": "cory.j.finger@gmail.com",
  "company_name": "Crystal",
  "location": "Seattle",
  "text_sample": "Something",
  "text_type": "various"
}'
# Create the query
query = {
  first_name: "Drew",
  last_name: "D'Agostino",
  email: "drew@crystalknows.com",
  company_name: "Crystal",
  location: "Nashville, TN",
  text_sample: "I, Drew, Founder of Crystal, think that ...",
  text_type: "various"
}

# Send the profile request to Crystal
profile_request = CrystalSDK::Profile::Request.from_search(query)

# You have access to the Request ID (if needed)
profile_request_id = profile_request.id
// Create the query
const query = {
  first_name: "Drew",
  last_name: "D'Agostino",
  email: "drew@crystalknows.com",
  company_name: "Crystal",
  location: "Nashville, TN",
  text_sample: "I, Drew, Founder of Crystal, think that ...",
  text_type: "various"
}

// Send the profile request to Crystal
CrystalSDK.Profile.Request.fromSearch(query)
  .then((profileRequest) => {

    // You have access to the Request ID (if needed)
    const profileRequestID = profileRequest.id
    ...
  })

Method: POST

Endpoint: /v1/profiles/async

Usage: Starts a profile request and returns the Request ID for later reference.

Request Type: application/json

Response Type: application/json


Note:

The Request Format to this endpoint is exactly identical to Request Format of the Profile Endpoint.

The difference lies in the fact that this (the Async Profile Endpoint) endpoint only starts a profile request and gives you the information needed to check on the status of the request.

The Profile Endpoint endpoint waits until the request has completed (or a reasonable amount of time) before returning a response.

The Request ID from this endpoint can be used with the Async Profile Results endpoint to receive a status (and, if finished, the profile results) of the search.

Request Format

Example Request Data

{
  "first_name": "Michael",
  "last_name": "Scott",
  "email": "michaelscott@dundermifflin.com",
  "company_name": "Dunder Mifflin",
  "location": "Scranton, PA",
  "text_sample": "Hey there, Jim! \nJust emailing to invite you and Pam to have dinner with Jan and I tonight!",
  "text_type": "email"
}
Param Type Description
first_name string First name of the person
last_name string Last name of the person
email string Email address of the person
company_name string Name of the company where the person works
location string Location of person. Formatting is ideally in the format of
Nashville, TN.
text_sample string A paragraph (or more) of text written by the person.
text_type string The origin of the text given in the text_sample. This can be one of:
["email", "various", "bio", "resume"].
  1. first_name and last_name

  2. email

  3. text_sample and text_type

Response Format

Example Response Data

{
  "request_id": "df584bb8-affb-46bb-832e-209315086973"
}

Listed below are the properties of a successful Profile Request creation.

Param Type Description
request_id string Profile Request ID to be used to retrieve the profile results from the Async Profile Results endpoint.

HTTP Status Codes

Listed below are the HTTP Status Codes that might be sent with a response:

Code Title Meaning
200 OK Not an error - just happy things!
401 Unauthorized Organization Token was invalid
429 Rate Limit Hit You’ve hit the rate limit for your plan
500 Unexpected Error An unexpected error occurred

Try It Out

...

...

Profile Results (Async)

Summary

Example Request

curl "https://connect.crystalknows.com/v1/profiles/results/d6e24893-6aaa-493f-ae36-9418f53869f9" \
     -H "X-Org-Token: $YOUR_ORG_TOKEN"
# Create the query
query = {
  first_name: "Drew",
  last_name: "D'Agostino",
  email: "drew@crystalknows.com",
  company_name: "Crystal",
  location: "Nashville, TN",
  text_sample: "I, Drew, Founder of Crystal, think that ...",
  text_type: "various"
}

# Send the profile request to Crystal
profile_request = CrystalSDK::Profile::Request.from_search(query)

# Pull out the Profile Request ID (string)
profile_request_id = profile_request.id

# Save the Request ID somewhere (DB, Queue, Hard Drive..)
...

# Later, pull up the Request ID and pull information about it
saved_req = CrystalSDK::Profile::Request.new(profile_request_id)

if saved_req.did_finish? && saved_req.did_find_profile?
  profile = saved_req.profile
  ...
end
// Create the query
const query = {
  first_name: "Drew",
  last_name: "D'Agostino",
  email: "drew@crystalknows.com",
  company_name: "Crystal",
  location: "Nashville, TN",
  text_sample: "I, Drew, Founder of Crystal, think that ...",
  text_type: "various"
}

// Send the profile request to Crystal
CrystalSDK.Profile.Request.fromSearch(query)
  .then((profileRequest) => {

    // Pull out the Request ID
    const profileRequestID = profileRequest.id

    // Save the Request ID somewhere (DB, Queue, Hard Drive..)
    ...
  })

// Later, pull up the Request ID and pull information about it
const savedReq = new CrystalSDK.Profile.Request(profileRequestID)

savedReq.didFinish()
  .then((finished) => (
    finished ?
    CrystalSDK.Profile.fromRequest(savedReq) :
    Promise.reject('Request not finished')
  ))
  .then((profile) => {
    ...
  })
  .catch((err) => console.log("No profile found:", err))

Method: GET

Endpoint: /v1/profiles/results/:request_id

Usage: Retrieve the status of an Async Profile Request

Request Type: Path Parameter

Response Type: application/json

Request Format

Example Request Data

{
  "request_id": "d6e24893-6aaa-493f-ae36-9418f53869f9"
}
Param Type Description
request_id string The ID of the Profile Request to be retrieved

Response Format

Example Response Data

{
  "status": "complete",
  "info": {
    "first_name": "Drew",
    "last_name": "D'Agostino",
    "disc_scores": {
      "type": "Ids",
      "confidence": 90
    },
    "disc_image": "https:\/\/www.crystalknows.com\/images\/learn\/disc\/ids_full.png"
  },
  "recommendations": {
    "emailing": {
      "overview": "This person is a gifted communicator who prioritizes relationships, and providing them with a new idea and a time\/place to follow up to discuss verbally will probably result in a fast response.",
      "phrases": [
        "Write with short casual language and abbreviations",
        "Don't take yourself too seriously",
        "Use emotionally expressive language",
        "Appeal to their feelings to drive them to action",
        "Use an emoticon :)"
      ]
    },
    "motivations": {
      "overview": "This person is <b>outgoing<\/b>, <b>optimistic<\/b>, and will encourage their colleagues to work hard, play hard. They thrives in workplaces that encourage <b>creativity<\/b>.",
      "phrases": [
        "New relationships",
        "Peer recognition",
        "Fun & excitement",
        "Feeling accepted",
        "Ambitious goals"
      ]
    },
    "communication": {
      "overview": "This person will appreciate a break in <b>momentum<\/b> to joke around and tell stories while getting to know their colleagues on a more personal level.",
      "phrases": [
        "Emphasize the future",
        "Use self-deprecating humor (don't act like you take yourself too seriously)",
        "Leave a conversation open-ended",
        "Tell a few jokes",
        "Exaggerate about any facts (not even a little bit)"
      ]
    },
    "behavior": {
      "overview": "This person will easily <b>build rapport<\/b> with those surrounding them. <b>Friendly<\/b>, <b>optimistic<\/b> and <b>eager<\/b>, their enthusiasm is contagious.",
      "phrases": [
        "Make a quick purchase decision",
        "Immediately feel comfortable speaking to a new person",
        "Focus on deep & close relationships rather than high quantity",
        "Make a decision more quickly than most people",
        "Forget something important"
      ]
    },
    "building_trust": {
      "overview": "This person might get bored by monotony, structure, and formality. Has a preference for <b>brainstorming<\/b>, often thinks out loud, and will look for feedback from their peers.",
      "phrases": [
        "Introduce them to others in your network",
        "Smile and make eye contact frequently",
        "Remember and ask about their personal details",
        "Challenge them on occasion",
        "Share your feelings frequently"
      ]
    },
    "selling": {
      "overview": "This person is decisive, energized by ideas, and overlooks details, so stick to the big picture and get to your point quickly. ",
      "phrases": [
        "Focus on the future plans for your product",
        "Try to schedule a meeting with other coworkers",
        "Use hyperbole to make a point (\"This is the best product in the world!\")",
        "Tell a past customer story instead of listing features",
        "Tell a story about the company instead of listing facts"
      ]
    },
    "working_together": {
      "overview": "This person is creative, decisive, a bit disorganized, overlooks details, and enjoys working with people.",
      "phrases": [
        "Confront conflict in person rather than via email",
        "Recognize their achievements verbally",
        "Express criticism in person or on the phone",
        "Express criticism via email",
        "Use purely logical appeals if you argue"
      ]
    },
    "overview": "This person is a gifted communicator, prioritizes relationships, and sometimes makes decisions based solely on instinct.",
    "qualities": [
      "Enterprising",
      "Influential",
      "Assertive",
      "Daring",
      "Charming"
    ]
  }
}

Listed below are the properties of a successful profile request result.

Param Type Description
status string Status of the call. One of the following:
["processing", "complete", "error"]
info string General information about the profile (see Profile Response Format)
recommendations string All of Crystal’s recommendations (see Profile Response Format)

HTTP Status Codes

Listed below are the HTTP Status Codes that might be sent with a response:

Code Title Meaning
200 OK Not an error - just happy things!
404 Not Found No profile was found that matched the search query
401 Unauthorized Organization Token was invalid
500 Unexpected Error An unexpected error occurred

Try It Out

...

...