_

Summary

This article will help configure an Open API and allow third-party applications to extract your data from your Crewhu account. It covers the following topics:

• Authentication
• API Base Address
• Endpoints
• Fields
  • Survey
  • User
  • Badge
  • Badge History
  • Prize
  • Prize History
• Response Examples
• Limit / Step
• Query Parameters
• Miscellaneous
• Response Codes & Errors
• Error Token Examples
• Examples

_

Authentication

Key: X_CREWHU_APITOKEN

Value: Copy the token by going to Settings > Integrations

 

 

Use the Key and Value on the Headers as shown.

^Top

_

API Base Address

PRODUCTION: https://api.crewhu.com/api/

_

Endpoints

• /v1/survey
• /v1/user
• /v1/badge
• /v1/badgehistory
• /v1/prize
• /v1/prizehistory

^Top

_

Fields

_

Survey 

Base GET Request: "https://api.crewhu.com/api/v1/survey"

Field Name	Type	Description
_id	IDString	Unique ID for this Survey
surveyTagsCustomer	[String]	Tags selected by the customer who answered the survey
surveyTagsCompany	[String]	Tags selected by a manager who reviewed the survey
comment	String	The feedback provided by the customer
closed	Date	Date/time that the survey has been answered at
survey_type_code	String	Type of Survey: typResolved, typReply, typSignature
ticket_num	String	Ticket number
customer_data	Object	Customer data (ID, name, contact name, email, phone)
employees	[IDString]	Users that have been selected by the customer
rating	String	Survey rating: 5 - Positive, 0 - Neutral, -5: Negative
rating_label	String	Custom rating label: POSITIVE, NEUTRAL, NEGATIVE (for instance)
reviewed	Boolen	Is this survey reviewed by a manager?
ip_address	String	IP address that answered the survey
_created_at	Date	Date/time the customer clicked the face and first opened the survey
_updated_at	Date	Date/time this survey has been modified
summary	String	The ticket summary/subject
inactive	Boolen	Is this survey inactive or deleted?

 

^Top

_

User/Employee  

Base GET Request: "https://api.crewhu.com/api/v1/user"

Field Name	Type	Description
_id	IDString	Unique ID for this Employee/User
employee_id	String	Employee ID from the ticket system
firstname	String	Employee/User first name
lastname	String	Employee/User last name
hiredate	Date	Date of Employee/User hiring
picture	String	URL for the Employee/User picture
location	String	Location which this Employee/User belongs to
department	String	Department which this Employee/User belongs to
position	String	Position which this Employee/User has
managed_locations	[String]	Locations which this Employee/User manages
managed_departments	[String]	Departments which this Employee/User manages

^Top

_

Badge

Base GET Request: "https://api.crewhu.com/api/v1/badge"

Field Name	Type	Description
name	string	badge name
description	string	badge description
imageClass	string
ima geFile	string

_

Badge History

Base GET Request: "https://api.crewhu.com/api/v1/badgehistory"

Field Name	Type	Description
badge	_id
badge_level	number
message	string
fromUser	_id
toUsers	[_id]
survey	_id
dateGiven	date
badgePoints	number
dateCancelled	date
userCancelled	_id
messCancelled	string

_

Prizes

Base GET Request: "https://api.crewhu.com/api/v1/prize"

Field Name	Type	Description
description	string
prizeURL	string
points	number
taxable	boolean
image	string

_

Prizes History

Base GET Request: "https://api.crewhu.com/api/v1/prizehistory"

Field Name	Type	Description
prize	_id
user	_id
date_redeem	date
date_cancel	date
points	number
quantity	number
status	string

^Top

_

Response Examples

{

   "_links": {

       "base": "[APIAddress]",                //The API Base Address

       "self": "/v1/survey?step=2&limit=100", //The current páge endpoint and parameters

       "prev": "/v1/survey?step=1&limit=100", //EMPTY when first

       "next": "/v1/survey?step=3&limit=100"  //EMPTY when last

   },

   "start": 101     //The start record

   "limit": 100,    //The limit for each step

   "size": 100,     //The size of this result set

   "total": 1024,   //The total number of records

   "results": [

       ...

   ],

}

^Top

_

Limit / Step

Default Limit: 100

Max Limit: 1000 (https://api.crewhu.com/api/v1/survey?limit=1000)

_

Pagination

Crewhu uses the Step parameter to paginate the results. i.e: https://api.crewhu.com/api/v1/survey?limit=10&step=2. 

 

Query Parameters

Query parameters should be passed as JSON Objects (see examples):

_updated_at: $gt (greater than), $gte (greater than or equal), $lt (less than), $lte (less than or equal)

inactive: true, false, undefined (means both active and inactive)

step: define the step for pagination purposes.

limit: define the result's size. Default limit: 100;  Max limit: 1000.

^Top

_

Miscellaneous

All Date/Times are UTC

_

Response Codes & Errors

• 200 OK
• 400 Bad Request
• 401 Unauthorized
• 403 Forbidden
• 404 Not Found
• 500 Internal Server Error

_

Error Token Examples

Error Token	Response Code
API_ERR_NO_AUTH_PARAM	401
API_ERR_INV_AUTH_PARAM	401
API_ERR_INACT_AUTH_PARAM	401
API_ERR_INVALID_QUERY	400
API_ERR_OUT_OF_BOUNDS	400

^Top

_

Examples

• https://api.crewhu.com/api/v1/survey
  Will bring all surveys, with a limit of 100, and step 1.

• https://api.crewhu.com/api/v1/survey?limit=10&step=3
  Will bring the 3rd step of a list of all surveys, using a limit of 10 for each step.

• https://api.crewhu.com/api/v1/survey?query={"inactive":true}
  Will bring all the inactive surveys.

• https://api.crewhu.com/api/v1/survey?query={"_updated_at":{"$gte":"2019-01-01T00:00:00.000Z","$lt":"2019-12-31T00:00:00.000Z"}}
  Will bring all surveys that have been updated between 01/01/2019 and 12/31/2019

• https://api.crewhu.com/api/v1/survey?query={"inactive":false,"_updated_at":{"$gte":"2019-07-01T00:00:00.000Z","$lt":"2019-12-31T00:00:00.000Z"}}
  Will bring only active surveys that have been updated between 07/01/2019 and 12/31/2019

^Top