User Management

Using the API, it is possible to integrate your master directory for user management with Showpad. This allows you to maintain a single source of truth in your master directory and manage Showpad user licenses from there.

In most cases, not every user in your master directory will be assigned to Showpad. Therefore, we advise creating a specific group that includes all Showpad entitled users. Any changes made to this group (i.e., adding, updating, or removing a user) should reflect in Showpad user management. This can be achieved by setting up a plugin that triggers an API call to Showpad whenever a user is added to, removed from, or updated in that user group.

Retrieving User Information

API Version

Most of the commands here must be used with API v3. However, using API v4 is highly recommended (when possible).

Getting user objects stored in Showpad is very straightforward. With a simple GET request, you can retrieve:

Request	Endpoint
A single user	https://{{subdomain}}.api.showpad.com/v4/users/{userId}
A list of users	https://{{subdomain}}.api.showpad.com/v4/users

See sample requests below:

# Get a single user
curl --request GET \
  --url https://{{subdomain}}.api.showpad.com/v4/users/c143c05d12c1433ba1358c7eb2e07c75 \
  --header 'Authorization: Bearer MyApiToken' \
  --header 'Content-Type: application/json'

# Get a list of users
curl --request GET \
  --url https://{{subdomain}}.api.showpad.com/v4/users \
  --header 'Authorization: Bearer MyApiToken' \
  --header 'Content-Type: application/json'

Check out the API Specification for more information regarding the API.

Create Users

API Version

API v3 must be used.

To add a user to Showpad, execute a POST request to:

https://{{subdomain}}.showpad.biz/api/v3/users.json

For a full overview of all data that can be passed on in the request body (e.g. license types, user roles, etc.), please refer to the API Specification.

Example

curl --request POST \
  --url https://{{subdomain}}.showpad.biz/api/v3/users.json \
  --header 'Authorization: Bearer MyApiToken' \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "bob.smith@showpad.com",
    "firstName": "Bob",
    "lastName": "Smith",
    "userName": "bob.smith@showpad.com",
    "isActive": true,
    "language": "en",
    "externalId": "customer-ab7320ec521e4783be92512b7e400eb7"
  }'

External ID

externalId is an optional attribute used when creating a user. This attribute is usually the ID of the user in the customer's user directory. It can be used to verify whether a user has already been added.

More significantly, it can be used in order to map an authenticated user to a Showpad user via an Authentication mechanism like SAML.

info

A successful request will return a 201 Created status code. If there was a problem with the data provided, a 4xx Client Error status code will be returned. It will respond a 409 Conflict status code if the user entity submitted already exists.

Update Users

API Version

API v3 must be used.

To update an existing user object, perform a PUT request to:

https://{{subdomain}}.showpad.biz/api/v3/users/{userId}.json

userId is the User ID of the user object to be modified. In the request body, provide the attributes that need to be updated.

For a full overview of all data that can be passed on in the request body (e.g. license types, user roles, etc.), please refer to the API Specification.

Example

curl --request PUT \
  --url https://{{subdomain}}.showpad.biz/api/v3/users/c143c05d12c1433ba1358c7eb2e07c75.json \
  --header 'Authorization: Bearer MyApiToken' \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "bob.smith@showpad.com",
    "firstName": "Bob",
    "lastName": "Smith",
    "userName": "bob.smith@showpad.com",
    "isActive": true,
    "language": "en"
  }'

Deactivate Users

API Version

API v3 must be used.

A user can be deactivated, using the same Update Users endpoint mentioned above:

PUT https://{{subdomain}}.showpad.biz/api/v3/users/{userId}.json

{userId} is the User ID of the user object to be deactivated. The important attribute here is to set isActive to false.

See the sample request below:

curl --request PUT \
  --url https://{{subdomain}}.showpad.biz/api/v3/users/c143c05d12c1433ba1358c7eb2e07c75.json \
  --header 'Authorization: Bearer MyApiToken' \
  --header 'Content-Type: application/json' \
  --data '{ "isActive": false }'

note

To reactivate a user, execute the same request with isActive set to true.

Delete Users

API Version

API v3 must be used.

irreversible action

Deleting a user will completely remove the user and all its related data from Showpad. Therefore, it might be a good idea to perform the deletion when the user is permanently removed from the master user directory. Showpad suggests using deactivation for all other purposes instead.

Deleting a user is as easy as calling:

DELETE https://{{subdomain}}.showpad.biz/api/v3/users/{userId}.json

{userId} is the User ID of the user object to be deleted.

Example

curl --request DELETE \
  --url https://{{subdomain}}.showpad.biz/api/v3/users/c143c05d12c1433ba1358c7eb2e07c75.json \
  --header 'Authorization: Bearer MyApiToken' \
  --header 'Content-Type: application/json'

User Authentication

For security reasons, it is obviously not advised to send the user password when creating a new user via our API. When no password is entered, an invitation mail is sent to the user so the user can enter his own password privately.

Authentication can also work via a Single Sign-On (SSO) service. This allows users to log in with their corporate accounts. You can find more information about authenticating with Showpad's API here and implementing SSO in our Help Center.