API
Uploading Users & Teams via the API
This feature allows you to upload a full list of your users to Crewmojo. You can automate this process so that Crewmojo is in sync with your employee management system in terms of active employee's/users and their basic details.
Endpoints:
Test
https://api.test.crewmojo.com/v1/integrations/upload/humans
Production
https://api.crewmojo.com/v1/integrations/upload/humans
Request Type:
POST
Content Type:
text/csv
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
Data format:
You can send Crewmojo CSV data in the body of the http POST.
The data elements Crewmojo is looking for are:
Data
Required
Format
firstName
Yes
String
lastName
Yes
String
emailAddress
Yes
String, must be valid email
employeeCode
No
String
managerEmployeeCode
No
String, can also be managerEmailAddress is employeeCodes are not present.
employmentStartDate
No
String, the employment start date is the date employment was started. Allowed formats are any combination of DD, MM and YYYY. Eg YYYY-MM-DD, or MM-DD-YYYY.
employmentEndDate
No
String, the employment end date is the date employment was terminated. If blank, then Crewmojo assumes employee is currently actively employed. Allowed formats are any combination of DD, MM and YYYY. Eg YYYY-MM-DD, or MM-DD-YYYY.
leaveStartDate
No
String, the start date of the next or most recent leave
leaveEndDate
No
String, the end date of the next or most recent leave
humanRole
No
String, if present, this must exactly match one of the human roles that have been previously been configured at the company settings within Crewmojo. Please note, it is possible to instruct Crewmojo to automatically create humanRole's that do not yet exist. This is not the default behaviour, but this can be achieved by adding the http header Crewmojo-AddHumanRoles - see below.
metaData
No
teamData
No
See 'Creating & Maintaining Teams' below'.
It is possible to also include human profile pictures in this upload. If this is something you would like to do, please contact us.
If employeeCode is present, then this is the 'primary key'. If employeeCode is not present then emailAddress is the 'primary key'. 'Primary key' is the unique identifier for the record.
By example:
If there is an employeeCode present we attempt to find an existing employee using employeeCode. If there is no employee found using employeeCode, we then try to find the employee using the email address. If we don't find the employee using the email address, we create a new record for the employee.
If managerEmployeeCode is present, then we will build the reporting hierarchy based upon the employee/manager relationships specified in the data.
Note: You can upload a full list of your users each time you upload, or only the users that have changed in your system.
Creating & Maintaining Teams:
We have three methods to create teams:
Reporting line teams - If managerEmployeeCode (or managerEmailAddress) is present we build a team with the manager as the team leader.
Non-reporting line teams - these can be additional columns added to the user file. This is fine for a few team types, but if there are more you need to use method 3.
A separate teams file - this allows for any number of teams per user. Please contact us for this option.
Notes:
If a data value does not exist, the Crewmojo API can handle blank values, nulls or the data can be non existent.
If you are uploading CSV and any column might contain a comma, then make sure you enclose the column with double quotes.
Upload Configuration:
There are two ways to define your upload file configuration:
Predefined schema stored on Crewmojo side. This is the recommended process and the configuration is developed by Crewmojo in consultation with you.
Supplying custom http header values. Only use this method if your schema changes regularly or to ensure a user of the Crewmojo application wont affect user uploads via API by changing the configuration. The custom http header values to supply are:
http Header
CSV
JSON
Values
Crewmojo-DateFormat
Yes
Yes
Any combination of DD, MM and YYYY
Crewmojo-SuppressInvitation
Yes
Yes
true or false. If true, then no invitation emails will be sent during upload. If false, then the invitation will be sent to all employees if they have not already been invited. Note that invitation emails can always be sent manually using the Crewmojo application at a later date.
Crewmojo-HeaderRow
Yes
No
true or false. If true, Crewmojo expects the CSV data has a header row.
Crewmojo-Mapping
Yes
No
This allows you to map your data to the data elements expected by Crewmojo. The mapping is a simple JSON array telling us which csv column index relates to the Crewmojo data element. Eg: [{"index":0,"field":"employeeCode"},{"index":2,"field":"lastName"},{"index":1,"field":"firstName"},{"index":3,"field":"emailAddress"}]
Crewmojo-AddHumanRoles
Yes
Yes
true or false. If this optional header value is true, then Crewmojo will automatically create any humanRole that does not yet exist within Crewmojo.
If you do not supply these header values, then the Crewmojo API will look for configuration that has been set within Crewmojo.
Our recommended process for invitations is to suppress invitations via the upload, and manually send invitations via Crewmojo application as needed. You can select multiple employees to send invitations to via Crewmojo application. This recommended process is more controlled and managed - especially when initially onboarding all your employees to Crewmojo.
Upload process:
The sequence of events are:
Upload data per directions above.
Crewmojo API will perform a pre-parsing phase to make sure the data is importable. Please note that even if some of the required fields are missing or invalid format, then Crewmojo will still accept the data and report on the invalid records of data in the receipt email sent, see below. The API will respond with a http 200 if your data upload has been successful. If you receive a value other than 200, then the data was not accepted and will not be processed. In the response from the API, to provide a little more information, you will also see the following JSON:
If accepted:
{"success":true}
If token invalid:
{"success":false,"httpErrorCode":401,"errorMessage":"Unauthorized"}
If internal Crewmojo error:
{"success":false,"httpErrorCode":500,"errorMessage":"Error queuing bulk human upload"}
If accepted, your data will be placed in a queue and processed as soon as possible.
Once processing is complete, a receipt email will be sent to all of your users that are listed as 'Administrators' within Crewmojo application. The receipt email will provide some statistics of the import and list the records that were not able to be imported due to missing or invalid data.
Last updated