Articles in this section

See more

Open API

Avatar
Stephen Spiegel
  • Updated
Follow

 _mceclip0.png

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

Key: X_CREWHU_APITOKEN

Value: Copy the token by going to Settings > Integrations

 OpenAPIToken.jpg

 

Use the Key and Value on the Headers as shown.

^Top

_

API Base Address

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

_

Endpoints

^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: 20

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

_

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: 20;  Max limit: 100.

Passing Query Parameters Programmatically

Filters such as _updated_at and inactive must be included inside a single parameter named query. The value of query must be formatted as a JSON string.

Do not pass _updated_at or inactive as standalone URL parameters. If they are sent separately, the filter will not be applied and the API will return unfiltered results.

For example, the following Python request retrieves surveys updated within a specified date range:

import json
import requests
crewhu_headers = {
   "X_CREWHU_APITOKEN": CREWHU_API_KEY,
   "Content-Type": "application/json"
}
crewhu_params = {
   "limit": 100,
   "step": 1,
   "query": json.dumps({
       "_updated_at": {
           "$gte": "2026-06-01T00:00:00.000Z",
           "$lt": "2026-06-30T00:00:00.000Z"
       }
   })
}
response = requests.get(
   f"{CREWHU_BASE_URL}v1/survey",
   headers=crewhu_headers,
   params=crewhu_params
)

In this example:

  • limit and step are passed as regular request parameters.
  • _updated_at is placed inside the query object.
  • json.dumps() converts the query object into the JSON string expected by the API.
  • All dates and times must use UTC.

For pagination, step starts at 1. Continue increasing its value until _links.next is no longer included in the response. The default limit is 20, and the maximum limit is 100.

^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 20, 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

Related articles

Comments

0 comments

Please sign in to leave a comment.