7/15/24, 5:34 PM

GET User(s)
The Users API allows you to retrieve, create and delete Users on the platform. This enables scenarios where users
created/maintained in other systems (e.g., SAP, Salesforce) can be replicated through the platform automatically. On the
Cloud, this API is available via SSL-secured HTTPS connection using the REST GET, POST and DELETE verbs.
The format query string parameter controls the desired response format. Specify either xml or json.
/api/v2/user?format=xml/json
To search for and retrieve multiple Users at once, use a GET with the search API found at:
/api/v2/user/search?format=xml/json
NOTE: This API end point implements pagination and, as such, you must cater for this when you connect to our
platform. You can learn more about pagination here.

GET Request
The GET verb allows you to retrieve a single User, identified by its unique ID. The required and optional parameters for a
GET call to the Users API are outlined below.
Parameter Data Requir
Description
Name Type ed
Specifies the desired format of the response
Format String Yes
Must either JSON or XML
Your unique Provider Id found on the Organization Setup page of the secure website
CompanyId Integer Yes
(under My Account)
Your unique Integration Key found on the Organization Setup page of the secure website
Integrationkey String Yes
(under My Account)
Id GUID The unique identifier of the User you wish to retrieve
or
Email string Yes The email address of the User to retrieve
or
ExternalId string The external identifier for the User to retrieve

GET Response
The data returned from a User GET is provided as follows:
User Response (<UserResponse>)
Field Name Data Type Description
User User The returned User object
ResponseStatusResponseStatusDetails of any errors that may have occurred

User (<User>)
Field Name Data Type Description
Id GUID Unique identifier of the User.
Your unique Company Id found on the Organization Setup page of the secure website
CompanyId Integer (under My Account).
Required for POST and PUTs
String External identifier of the User. Used to link this User to external systems. Can be
ExternalId
(Max length 50 chars)null/empty.
String User's first name.
FirstName (Max length 100 Required for POST actions. If not specified on PUTs, then field will not be updated by
chars) PUT.
String User's last name.
LastName (Max length 100 Required for POST actions. If not specified on PUTs, then field will not be updated by
chars) PUT.
Email String User's email address.
(Max length 200 Required for POST actions. If not specified on PUTs, then field will not be updated by

1/8
 7/15/24, 5:34 PM

chars) PUT.
Status of this User. Status options are:
Invited – User has been created and sent an invite to activate their account
Status String
Active – User has activated his account and is able to use the app
Inactive – User has been deactivated
DateTime Date and time the User's last activity on the platform.
LastActivity (YYYY-MM- Time zone is UTC; time is in 24 hour values.
DDTHH:MI:SS) The “T” in the format is a delimiter.
Optional. Array of GUIDs for the respective folders that the User is permitted access
Folders Array of GUID
to.
Groups Array of GUID Optional. Array of GUIDs for the respective groups that the User belongs to.
Optional. The website access role (if any) of this User.
If blank, the User has no access to the website.
Role options are:
WebsiteRoleString
Admin – User has administrative level access on the website
User – User has non-admin, editing access to the website
ReadOnly – User has read-only access to the website
List of UserDevice - the devices that this User has used to access the app.
UserDevicesUserDevices
Only available on GET responses, cannot be set by POST or PUTs
The password to set for the User.
Password String Optional, if blank then a random password is generated.
Only applicable for POST and PUT actions.
Whether or not to send the User an activation email.
DoNotEmail Boolean
Only applicable for POSTs and PUTs.

Whether or not to reset the User's password.

This will generate a random password and send a re-activation email to the User by
ResetPassw default.
Boolean
ord If DoNotEmail is set to True, then no email will be sent.
If Password is specified, then that will be used as the new password value.
Only applicable for PUTs.
Your unique Integration Key found on the Organization Setup page of the secure
IntegrationK
String website (under My Account)
ey
Required for POST and PUT requests.
UserDevice (<UserDevice>)
Field NameData TypeDescription
Id GUID The unique identifier that our platform has assigned this device
Hardware String Description of the device hardware
OS String The operating system of the device
OSVersion String The version number of the operating system
Response Status (<ResponseStatus>)
Input NameData TypeDescription
ErrorCode String The error code/message for the failure
Message String Description of the error
Errors Collection Collection of ResponseErrors compiled during the request
Response Error (<ResponseError>)
Input NameData TypeDescription
ErrorCode String The error code/message for the failure
FieldName String Name of field involved in error, if any
Message String Error message

API Usage Example

Given that the API is REST based, you can access the API directly via your web browser to test it. Obviously for actual
integration works, you will need to make a web request to the given REST URL and then parse the response.
Below is a simple GET example which gets a User, using XML format.
GET Request
/api/v2/[email protected]&integrationkey=xxxxxxxxxxxx&companyid=1&format=xm

2/8
 7/15/24, 5:34 PM

XML Response
<UserResponse>
<ResponseStatus>
<Errors>
<ResponseError>
<ErrorCode>String</ErrorCode>
<FieldName>String</FieldName>
<Message>String</Message>
</ResponseError>
</Errors>
</ResponseStatus>
<User>
<CompanyId>0</CompanyId>
<Email>String</Email>
<ExternalId>String</ExternalId>
<FirstName>String</FirstName>
<Folders>
<Id>00000000-0000-0000-0000-000000000000</Id>
</Folders>
<Groups>
<Id>00000000-0000-0000-0000-000000000000</Id>
</Groups>
<Id>00000000-0000-0000-0000-000000000000</Id>
<IntegrationKey>String</IntegrationKey>
<LastActivity>0001-01-01T00:00:00</LastActivity>
<LastName>String</LastName>
<UserDevices>
<UserDevice>
<Hardware>String</Hardware>
<Id>00000000-0000-0000-0000-000000000000</Id>
<OS>String</OS>
<OSVersion>String</OSVersion>
</UserDevice>
</UserDevices>
<Status>String</Status>
<WebsiteRole>String</WebsiteRole>
</User>
</UserResponse>

3/8
 7/15/24, 5:34 PM

POST User
TABLE OF CONTENTS
POST Request
POST Response
User Response ()
User () Response Fields
API Usage Example
POST Request
You may use either JSON or XML formats in your request. You indicate this by setting the ContentType HTTP header as
"application/json" or "application/xml." If no ContentType is specified, XML format is assumed. The required and optional
parameters for a POST to the Users API are outlined below.
Parameter Data Require
Description
Name Type d
The User that you wish to create. See the User type definition from the GET
User User Yes
above.
POST Response
The data returned from a User POST is provided as follows:
User Response (<UserResponse>)
Field Name Data Type Description
User User The User created
ResponseStatusResponseStatusDetails of any errors that may have occurred
User (<User>) Response Fields
The User returned is only populated with the following fields:
Field NameData TypeDescription
Id GUID Unique identifier of the new User
Status String Status of this User which will be set to Invited

API Usage Example

Given that the API is REST-based, you can access the API directly via your web browser to test it. Obviously for actual
integration works, you will need to make a web request to the given REST URL and then parse the response. Below is a
simple POST example which creates a User, using XML format.

<User>
<CompanyId>0</CompanyId>
<Email>String</Email>
<ExternalId>String</ExternalId>
<FirstName>String</FirstName>
<Folders>
<Id>00000000-0000-0000-0000-000000000000</Id>
</Folders>
<Groups>
<Id>00000000-0000-0000-0000-000000000000</Id>

4/8
 7/15/24, 5:34 PM

</Groups>
<Id>00000000-0000-0000-0000-000000000000</Id>
<IntegrationKey>String</IntegrationKey>
<LastName>String</LastName>
<Password>String</Password>
<Status>String</Status>
<WebsiteRole>String</WebsiteRole>
</User>

XML Response
<UserResponse>
<User>
<Id>00000000-0000-0000-0000-000000000000</Id>
<Status>String</Status>
</User>
<ResponseStatus>
<ErrorCode>String</ErrorCode>
<Message>String</Message>
<Errors>
<ResponseError>
<ErrorCode>String</ErrorCode>
<FieldName>String</FieldName>
<Message>String</Message>
</ResponseError>
</Errors>
</ResponseStatus>
</UserResponse>

5/8
 7/15/24, 5:34 PM

PUT User
TABLE OF CONTENTS
PUT Request
User Response ()
User () Response Fields
API Usage Example
PUT Request
The PUT verb allows you to update a single, existing User on the platform. You may use either JSON or XML formats in
your request. You indicate this by setting the ContentType HTTP header as "application/json" or "application/xml." If no
ContentType is specified, XML format is assumed. The required and optional parameters for a PUT to the Users API are
outlined below.
Parameter NameData TypeRequiredDescription
The User that you wish to update
User User Yes
See the User type definition from the GET above
PUT Response
The data returned from a User PUT is provided as follows:
User Response (<UserResponse>)
Field Name Data Type Description
User User The User created.
ResponseStatusResponseStatusDetails of any errors that may have occurred
User (<User>) Response Fields
The User returned is only populated with the following fields:
Field NameData TypeDescription
Id GUID Unique identifier of the new User
Status String Status of this User which will be set to Invited
API Usage Example
Given that the API is REST-based, you can access the API directly via your web browser to test it. Obviously for actual
integration works, you will need to make a web request to the given REST URL and then parse the response.
Below is a simple PUT example which updates an existing User, using XML format.

<User>
<CompanyId>0</CompanyId>
<Email>String</Email>
<ExternalId>String</ExternalId>
<FirstName>String</FirstName>
<Folders>
<Id>00000000-0000-0000-0000-000000000000</Id>
</Folders>
<Groups>
<Id>00000000-0000-0000-0000-000000000000</Id>
</Groups>
<Id>00000000-0000-0000-0000-000000000000</Id>

6/8
 7/15/24, 5:34 PM

<IntegrationKey>String</IntegrationKey>
<LastName>String</LastName>
<Password>String</Password>
<Status>String</Status>
<WebsiteRole>String</WebsiteRole>
</User>

XML Response

<UserResponse>
<User>
<Id>00000000-0000-0000-0000-000000000000</Id>
<Status>String</Status>
</User>
<ResponseStatus>
<ErrorCode>String</ErrorCode>
<Message>String</Message>
<Errors>
<ResponseError>
<ErrorCode>String</ErrorCode>
<FieldName>String</FieldName>
<Message>String</Message>
</ResponseError>
</Errors>
</ResponseStatus>
</UserResponse>

7/8
 7/15/24, 5:34 PM

DELETE User
DELETE Request
The DELETE verb allows you to delete a single User. Our platform will immediately remove the User from the platform.
You may use either JSON or XML formats in your request.
You indicate this by setting the ContentType HTTP header as "application/json" or "application/xml". If no ContentType is
specified, XML format is assumed.
The required and optional parameters for a DELETE to the User API are outlined below.
Parameter Data Require
Description
Name Type d
The User that you wish to create. See the User type definition from the GET
User User Yes
above.
User (<User>) Required Fields
The following fields must be specified when issuing a DELETE request to the User API.
All other fields will be ignored.
Data
Field Name Description
Type
IntegrationK Your unique Integration Key found on the Organization Setup page of the secure website (under
String
ey My Account)
Your unique Provider Id found on the Organization Setup page of the secure website (under My
CompanyId Integer
Account)
Id GUID Unique identifier of the User. You would have received this when creating the User via POST.
DELETE Response
If the DELETE update is successful, a 200 HTTP status is returned along a UserResponse.
If the DELETE is unsuccessful, a 400 HTTP status is returned along with a UserResponse.
User Response (<UserResponse>)
Field Name Data Type Description
ResponseStatusResponseStatusDetails of any errors that may have occurred

8/8