Skip to main content

User Provisioning API

These API endpoints allows the admin to manage their users and groups programmatically.

info

Before using the API, please obtain the API key by following the instructions here.

User Operations​

Get all users in a tenant with full information​

Sample request:

GET /users.json

Sample response:

[
  {
    "id": 1,
    "name": "Analyst",
    "email": "[email protected]",
    "role": "analyst",
    "initials": "An",
    "is_deleted": false,
    "is_activated": true,
    "has_authentication_token": true,
    "groups": [
      {
        "id": 33,
        "name": "Capital",
        "created_at": "2015-06-29T03:22:14.842Z",
        "updated_at": "2015-06-29T03:22:14.842Z",
        "tenant_id": 5
      }
    ],
    "allow_authentication_token": true,
    "current_sign_in_at": "2018-10-23T03:35:47.353Z",
    "last_sign_in_at": "2018-10-22T03:21:52.393Z"
  },
  {
    "id": 2,
    "name": "Business User",
    "email": "[email protected]",
    "role": "business",
    "initials": "Bu",
    "is_deleted": false,
    "is_activated": true,
    "has_authentication_token": false,
    "groups": [],
    "allow_authentication_token": false,
    "current_sign_in_at": "2018-10-21T03:35:47.353Z",
    "last_sign_in_at": "2018-10-20T03:21:52.393Z"
  },
]
note
  • current_sign_in_at: latest sign-in timestamp.
  • last_sign_in_at: previous sign-in timestamp (before the current_sign_in_at time).
  • allow_authentication_token is used to determine whether a user is allowed for API access (only Admin can update this field for a specific user).
  • has_authentication_token is used for determining whether a user has already generated an API access key (this flag will be turned to false if the Revoke Authentication Token call is requested).
  • A Tenant is the organization that is using Holistics (e.g. Grab).

Invite a new user to Holistics​

Sample request:

POST /users/invite.json

Parameters:

  • name: user's full name
  • email: user's email address
  • role: role: user role. At Holistics, there are 4 roles: admin, analyst, explorer, viewer (more about Holistics' permission system at https://docs.holistics.io/docs/permission-system).
  • message: The invitation message that will be sent to the invitee.

Sample request body:

{
  "name": "Test",
  "email": "[email protected]",
  "role": "user",
  "message": "Hey, let's join MyCompany workspace on Holistics"
}

Sample success response:

{
  "status": "ok"
}

Sample error response when a user already exists in Holistics's database: 

{
  "errors": [
    "Email already existed"
  ]
}

You will need to use the Resend Invitation API instead.

Resend invitation to user​

Sample request:

POST /users/user_id/resend_invite.json

Sample success response:

{
  "status": "ok"
}

Soft-delete a user​

Sample request:

DELETE /users/user_id.json

Sample success response:

{
  "status": "ok"
}

Restore a deleted user​

Sample request:

POST /users/restore.json

Sample request body:

{
  "id": 560
}

Sample error response when attempt to restore a non-deleted user:

{
  "errors": [
    "User is not deleted"
  ]
}

Allow/ Revoke a user's API access​

Sample request:

PATCH /users/user_id.json

Sample body request:

{
  "allow_authentication_token": true
}

Sample success response:

{
  "status": "ok"
}

Revoke Authentication Token from a user​

Sample request:

POST /users/user_id/revoke_authentication_token.json

Sample success response:

{
  "status": "ok"
}

Check whether email address is already used for a user in Holistics​

Sample request:

GET /users/check_holistics_user.json/?email={email_address}

Sample success response:

{
  "is_already_user": true
}

Change user role in Holistics​

Required params:

  • user_id
  • user: an object that contains the needed information for changing user role
    • role (string): can be admin, analyst or user
    • remove_groups (boolean): false by default. If the params are set to true, then the user's groups will also be removed after the role is changed.

Sample request:

POST /users/change_user_role.json

Sample body request:

{
    id: 1,
    user: {
        role: "analyst",
        remove_groups: true
    }
}

Find user by email address​

Sample request:

GET /users/get_user.json/?email={email_address}

Sample success response:

{
    "id": 1,
    "name": "Business User",
    "email": "[email protected]",
    "role": "business",
    "title": null
}

Group Operations​

Get all groups in a tenant​

Sample request:

GET /groups.json

Sample response:

[
  {
    "id": 1,
    "name": "Singapore",
    "num_user": 2
  },
  {
    "id": 2,
    "name": "Vietnam",
    "num_user": 2
  },
  {
    "id": 3,
    "name": "Indonesia",
    "num_user": 0
  }
]

Create a new group​

Sample request:

POST /groups.json

Sample body request:

{
  "group":{
    "name" : "Test"
  }
}

Sample success response:

{
  "id": 1,
  "name": "Test",
  "created_at": "2018-09-07T09:18:43.742Z",
  "updated_at": "2018-09-07T09:18:43.742Z",
  "tenant_id": 5
}

Update information of an existing group​

Sample request:

PUT /groups/group_id.json

Sample body request:

{
  "group":{
    "name" : "New Group Name"
  }
}

Delete an existing group​

Sample request:

DELETE /groups/group_id.json

Add a user into a group​

Sample request:

PUT /groups/group_id/user/user_id

Sample success response:

{
  "status": "OK"
}

Remove a user from a group​

Sample request:

DELETE /groups/34/user/454

Sample success response:

{
  "status": "OK"
}