User API | Insites Help Center

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.