User API

Warning

This is a legacy API. It is still functional but is not in active development/ maintenance anymore.

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

How to use these API endpoints

Obtain API Key

Before using the API, please obtain the API key by following the Getting Started guide.

Send API requests to Holistics

To use these APIs, simply append Holistics' host URL secure.holistics.io with your chosen endpoint.

For example, to call the API Get all users in a tenant with full information, you will have to use GET request with this URL: secure.holistics.io/user.json.

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: user role. At Holistics, there are 4 roles: admin, analyst, explorer, viewer.To learn more about the role system, visit User Roles.
• 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

This API is used to revoke generated Authentication Tokens. Consider using this API if:

• You are worried that the current token may have been leaked.
• You want to enforce a token refresh for security reasons.

After their token has been revoked, the user would need to re-generate a new token by following the Getting Started guide.

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
}