API

Downloading Data and Reports via the API

This feature allows you to download data and reports using the Crewmojo API. You can automate this process so that you can get a consistent stream of data and statistics for your system. For example, to populate a B.I. platform.

Endpoints:

EnvironmentURL

Test

https://api.test.crewmojo.com/v1/integrations/download/*

Production

https://api.crewmojo.com/v1/integrations/download/*

Request Type:

POST

Content Type:

text/csv

The reports are returned in csv format with the first row being the column headings.

Security:

The API will only accept encrypted connections over TLS (https).

Retrieve a short-lived Access Token (see here). You need to add this token to the 'Authorization' header of your HTTP POST:

  • Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cC...7rZ43t

Request Path:

ValueDescription
/v1/integrations/download/rrrrrrrr

rrrrrrr is the report identifier. Please speak to us about reports that you can access for your solution.

Request Body:

ValueTypeDescription

startDate

numeric, yyyymmdd format (optional)

start and end dates need to be present together

endDate

numeric, yyyymmdd format (optional)

start and end dates need to be present together

jobId

bool, true or false (optional)

Setting this value to true will force the report server to delay 30 seconds and return a jobId. This is useful for testing long running report process - see below.

Each data report is identified by a string which is appended to the above endpoint paths.

For example, to get a summary of 1:1's completed over a date range, the request would be something like this:

curl -X POST 'https://api.crewmojo.com/v1/integrations/download/oneonone.summary' 
-H 'accept: application/json' 
-H 'Content-Type: application/x-www-form-urlencoded' 
-H 'Authorization: Bearer access.token.here' 
-d '{"startDate":20240101,"endDate":20241231}'

Response:

CodeDescription / Example

200

Success, report data returned immediately

Content-Type: text/csv

Employee,Employee Code,Email,Manager,Manager Code,Active,Created Date,Invitation,Last Access,Employment Start,Employment End,Last 1-on-1 (12 months),Last Team Meeting (12 months),Active Teams,Active Hitchhiker's Guide Teams,Active Strategy and Planning Teams,Active Stars Only Teams,Active Division  Teams,Active Division  Teams,Current Position,Position History,Leave History,Gender,Home Address,State,Nickname,Relevant links,Mentor,Sparkle Factor,D.O.B,Security training
Adelina Amador,emp3,adelina.amador@test.crewmojo.com,James Fly,RTYUIOP,No,20200115,0,0,0,0,0,0,,,,,,,,,,,,,,,,,,
Adrian Willard,emp22,adrian.willard@test.crewmojo.com,James Fly,RTYUIOP,No,20210629,20221031,0,20130812,0,0,0,- Nat. Team Co-ordinators,,- Construction,,,,Mechanical Plant Engineer,- Mechanical Plant Engineer (29 Jun 2021),,,,,,,,,,
Alan Fink,emp6,alan.fink@test.crewmojo.com,James Fly,RTYUIOP,No,20200115,0,0,0,0,0,0,,,,,,,Mechanical Plant Engineer,,,,,,,,,,,

200

Log running report (after 30 seconds). See below for further action.

Content-Type: application/json

{
  "success": "true",
  "jobId": "cab1790ced8c44e47f7c5d087f19bb66"
}

400

Invalid data error

Content-Type: application/json

{
  "success": "false",
  "httpErrorCode": 400,
  "errorMessage": "Invalid data received"
}

401

Unauthorized error

Content-Type: application/json

{
  "success": "false",
  "httpErrorCode": 401,
  "errorMessage": "Unauthorized"
}

500

Internal Server Error

Content-Type: application/json

{
  "success": "false",
  "httpErrorCode": 500,
  "errorMessage": "Error generating report"
}

Please speak to us about the reports available and their corresponding identifiers.

Long running reports

If a report takes longer than 30 seconds to generate, then it is considered a long running report. In this case, the report API will return a jobId which you will then use to poll for a result.

Each jobId will expire 10 minutes after the original request. Make sure you retrieve the report data before this time.

Endpoints:

EnvironmentURL

Test

https://api.test.crewmojo.com/v1/integrations/download/*

Production

https://api.crewmojo.com/v1/integrations/download/*

Request Type:

GET

Content Type:

text/csv

The reports are returned in csv format with the first row being the column headings.

Security:

Same security as above

Request Path:

ValueDescription
/v1/integrations/download/rrrrrrrr?jobId=jjjjjjj

rrrrrrr is the report identifier. Please speak to us about reports that you can access for your solution. jjjjjjj is the jobId

Response:

The possible responses are the same as the initial request responses.

If the total time exceeds 5 minutes, then abandon the report request and try again. If this continues, please contact us.

Last updated