Provision user accounts via the API

How to create a user record via REST API on the Skedulo Pulse Platform.

The /onboarding/provision endpoints import user data, adds their credentials to Auth0, and sends out the Skedulo onboarding email to their provided email address.

Prerequisite

The Onboarding API includes the following endpoints:

Endpoint Operation Description
/onboarding/provision/standalone/users POST Each new user created can be automatically sent an invitation email, which contains a link allowing them to set a password.
/onboarding/provision/standalone/users PATCH Update a user record and the linked resource record, if applicable.

Provision users in a REST API request body

You can provision a user by sending the JSON data for the profile you want to create directly to the /onboarding/provision/standalone/users endpoint using the POST method.

Example request and response

The following example request creates a new user profile with the Scheduler role:

[
	{
		"email": "new_user@skedulo.com",
		"firstName": "New",
		"lastName": "User",
		"roles": ["Scheduler"],
		"sendInvitation": true
	}
]

If the request is successful, the response looks something like this:

{
	"result": {
		"inserted": 1,
		"updated": 0,
		"total": 1,
		"failures": {}
	}
}

Check the status of a provisioning request

You can check the status of your resource provisioning request using a GET request that references the taskId:

{
  "result": {
    "task": {
      "taskId": 85,
      "tenantId": "sk_1d8b120bc51d4ce7af222bd63f385155",
      "type": "bulk_user_import",
      "createdAt": "2019-09-26T04:46:43.011418Z",
      "lastCheckedInAt": "2019-09-26T04:46:46.021069Z",
      "completedAt": "2019-09-26T04:46:46.873375Z",
      "success": true,
      "errorMsg": null
    },
    "users": [
      {
        "email": "gemma+test701@skedulo.com",
        "taskId": 85,
        "firstName": "Admin",
        "lastName": "User",
        "success": true,
        "errorMsg": null
      },
      {
        "email": "ghilton+test702@skedulo.com",
        "taskId": 85,
        "firstName": "NewResource",
        "lastName": "User",
        "success": true,
        "errorMsg": null
      }
    ]
  }
}

The response shows that both resources were created successfully and also includes timestamps for the request and its completion.

Troubleshooting

Email already exists

Users listed in the API request must have a unique email address that does not already exist in the Skedulo system. If an email address is already associated with a Skedulo user, the resource will not be created, and the following error message will appear for that user in the task information:

{
	"result": {
		"inserted": 0,
		"updated": 0,
		"total": 1,
		"failures": {
			"jsmith@email.com": {
				"code": "email_already_exists",
				"message": "A user with that email already exists"
			}
		}
	}
}

Users need resource role

As a minimum, resources require a valid RegionId. Provisioning resources from a JSON file requires both a valid RegionId, as well as the isActive field (set to true).

Failing to provide this information in the resource file results in the following error message in response to the cURL request:

{
  "errorType": "users_need_resource_role",
  "message": "Users with an assigned resource must have Resource role and vice versa. Email of user records in error: {$email_address}"
}

The message field provides information about the error.

API user not set

The following error occurs if there is no API user set for your organization:

{
  "errorType": "api_user_not_found",
  "message": "API User for tenant sk_00000000aaaaa0000a00 has not been set up.",
  "tenantId": "sk_00000000aaaaa0000a00"
}

You must configure an API user for your organization using the Skedulo web application before you can make API requests.