icon right arrow Back to home
Integrations / API

User API

This page explains how to use our API to list, add, update and delete users in Insites.

All requests to our API should be authenticated. Our API is RESTful and communicates using JSON.

Fetch a list of existing users

Method: GET
Endpoint: https://api.insites.com/api/v1/users

Example

curl "https://api.insites.com/api/v1/users" --header "api-key: [YOUR API KEY]"

Expected response

If successful, you would expect a 200 response, with a body like this:

{
   "users":[
      {
         "roles":"user",
         "name":"Joe Bloggs",
         "account":"my_prospect_account_id",
         "username":"joebloggs@org.com",
         "email":"joebloggs@org.com",
         "createdAt":"2016-08-12T21:04:41+00:00",
         "forcePasswordChange":"0",
         "accounts":[
            "my_prospect_account_id",
            "my_secondary_prospect_account_id"
         ],
         "current":false
      },
      {
         "roles":"user",
         "name":"John Smith",
         "account":"my_prospect_account_id",
         "username":"johnsmith@org.com",
         "email":"johnsmith@org.com",
         "createdAt":"2016-08-12T21:04:41+00:00",
         "forcePasswordChange":"0",
         "accounts":[
            "my_prospect_account_id"
         ],
         "current":false
      }
   ]
}

All possible responses

Code Reason
200 List of users.

Fetch a specific user

Method: GET
Endpoint: https://api.insites.com/api/v1/user/[EMAIL]

Example

curl "https://api.insites.com/api/v1/user/[EMAIL]" --header "api-key: [YOUR API KEY]"

Expected response

If successful, you would expect a 200 response, with a body like this:

{
   "user":{
      "roles":"user",
      "name":"John Smith",
      "account":"my_prospect_account_id",
      "username":"johnsmith@org.com",
      "email":"johnsmith@org.com",
      "createdAt":"2016-08-12T21:04:41+00:00",
      "forcePasswordChange":"0",
      "accounts":[
         "my_prospect_account_id"
      ],
      "current":false
   }
}

All possible responses

Code Reason
200 User details returned.
403 User not found OR belongs to another Insites account.

Add a new user

Method: POST
Endpoint: https://api.insites.com/api/v1/user
Request body should be JSON encoded, and can include the following fields:

Property Definition Required
username String – This user’s email address (note: Insites only supports email addresses as usernames at this time). Yes
name String – The name of the user (e.g. Joe Bloggs). Yes
role String – The role for this user (one of ‘user’, ‘advanceduser’, ‘admin’). Yes
password String – The password for this user (minimum 8 characters). Yes
forcePasswordChange Boolean – if true, the user must change their password on next login. No (defaults to false)
jobTitle String – employee job title. No
phone String – employee phone number. No
accounts String array – a list of the accounts this user may access, where multi-account log in is enabled for your Insites account. No
[account_name]_[custom_field_name] String – Pass additional values to set as one of your custom user fields, e.g. employee ID or department (must be activated by your Insites account manager). No

Example

curl "https://api.insites.com/api/v1/user" --header "api-key: [YOUR API KEY]" --data "{"username":"[EMAIL]","name":"[NAME]","password":"[PASSWORD]","role":"[USER ROLE]"}"

Expected response

If successful, you would expect a 201 response, with a body containing the new user record like this:

{
   "user":{
      "roles":"user",
      "name":"John Smith",
      "account":"my_prospect_account_id",
      "username":"johnsmith@org.com",
      "email":"johnsmith@org.com",
      "createdAt":"2016-08-12T21:04:41+00:00",
      "forcePasswordChange":"0",
      "accounts":[
         "my_prospect_account_id"
      ],
      "current":false
   }
}

All possible responses

Code Reason
201 User created.
400 Missing data required to create a user.
400 There is an issue with your request, e.g. missing data required to create a user or invalid role.
403 This action is not permitted with the API credentials you are using.

Update an existing user

Method: PUT
Endpoint: https://api.insites.com/api/v1/user/[EMAIL]
Request body should be JSON encoded, and can include the following fields:

Property Definition Required
name String – The name of the user (e.g. Joe Bloggs). No (defaults to existing value)
role String – The role for this user (one of ‘user’, ‘advanceduser’, ‘admin’). No (defaults to existing value)
password String – The password for this user (minimum 8 characters). No (defaults to existing value)
forcePasswordChange Boolean – if true, the user must change their password on next login. No (defaults to existing value)
jobTitle String – employee job title. No (defaults to existing value)
phone String – employee phone number. No (defaults to existing value)
accounts String array – a list of the accounts this user may access, where multi-account log in is enabled for your Insites account. No (defaults to existing value)
[account_name]_[custom_field_name] String – Pass additional values to set as one of your custom user fields, e.g. employee ID or department (must be activated by your Insites account manager). No (defaults to existing value)

Example

curl -X PUT "https://api.insites.com/api/v1/user/[EMAIL]" --header "api-key: [YOUR API KEY]" --data "{"name":"[NAME]","password":"[PASSWORD]","role":"[USER ROLE]"}"

Expected response

If successful, you would expect a 200 response, with a body containing the updated user record like this:

{
   "user":{
      "roles":"user",
      "name":"John Smith",
      "account":"my_prospect_account_id",
      "username":"johnsmith@org.com",
      "email":"johnsmith@org.com",
      "createdAt":"2016-08-12T21:04:41+00:00",
      "forcePasswordChange":"0",
      "accounts":[
         "my_prospect_account_id"
      ],
      "current":false
   }
}

All possible responses

Code Reason
200 User updated.
400 Missing data required to create a user.
400 There is an issue with your request, e.g. missing data required to create a user or invalid role.
403 This action is not permitted with the API credentials you are using.

Delete an existing user

Method: DELETE
Endpoint: https://api.insites.com/api/v1/user/[EMAIL]

Example

curl -X "DELETE" "https://api.insites.com/api/v1/user/[EMAIL]" --header "api-key: [YOUR API KEY]"

Expected response

If successful, you would expect a 200 response, with a body like this:

{
    "deleted": true
}

All possible responses

Code Reason
200 User deleted.
403 User not found OR belongs to another Insites account.
  • Was this helpful?
  • Yes   No

Contact our
support team

Contact