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:

Environment	URL
Test	https://api.test.crewmojo.com/v1/integrations/upload/human
Production	https://api.crewmojo.com/v1/integrations/upload/human

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	Any number of meta data items can be included against each user record. Please contact us to assist with setting this up.
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:

1. Reporting line teams - If managerEmployeeCode (or managerEmailAddress) is present we build a team with the manager as the team leader.

2. 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.

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:

1. Predefined schema stored on Crewmojo side. This is the recommended process and the configuration is developed by Crewmojo in consultation with you.

2. 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:

1. Upload data per directions above.

2. 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"}

3. If accepted, your data will be placed in a queue and processed as soon as possible.

4. 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.