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 in our API overview.


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 Name
Data Type
Required
Description
Format
String
Yes
Specifies the desired format of the response.
Must either JSON or XML.
CompanyId
Integer
Yes
Your unique Provider Id found on the Organization Setup page of the secure website (under My Account)
Integrationkey
String
Yes
Your unique Integration Key found on the Organization Setup page of the secure website (under My Account)
Id
or
Email
or
ExternalId
GUID

string

string
Yes
The unique identifier of the User you wish to retrieve

The email address of the User to retrieve

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
ResponseStatus
ResponseStatus
Details of any errors that may have occurred

 

User (<User>)

Field Name
Data Type
Description
Id
GUID
Unique identifier of the User.
CompanyId
Integer
Your unique Company Id found on the Organization Setup page of the secure website (under My Account).
Required for POST and PUTs
ExternalId
String
(Max length 50 chars)
External identifier of the User.  Used to link this User to external systems. Can be null/empty.
FirstName
String
(Max length 100 chars)
User's first name.
Required for POST actions.  If not specified on PUTs, then field will not be updated by PUT.
LastName
String
(Max length 100 chars)
User's last name.
Required for POST actions.  If not specified on PUTs, then field will not be updated by PUT.
Email
String
(Max length 200 chars)
User's email address.
Required for POST actions.  If not specified on PUTs, then field will not be updated by PUT.
Status
String
Status of this User.  Status options are:
Invited – User has been created and sent an invite to activate their account
Active – User has activated his account and is able to use the app
Inactive – User has been deactivated
LastActivity
DateTime
(YYYY-MM-DDTHH:MI:SS)
Date and time the User's last activity on the platform.
Time zone is UTC; time is in 24 hour values.
The “T” in the format is a delimiter.
Folders
Array of GUID
Optional. Array of GUIDs for the respective folders that the User is permitted access to.
Groups
Array of GUID
Optional. Array of GUIDs for the respective groups that the User belongs to.
WebsiteRole
String
Optional. The website access role (if any) of this User.  
If blank, the User has no access to the website.
Role options are:
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
UserDevices
UserDevices
List of UserDevice - the devices that this User has used to access the app.
Only available on GET responses, cannot be set by POST or PUTs
Password
String
The password to set for the User.
Optional, if blank then a random password is generated.
Only applicable for POST and PUT actions.
DoNotEmail
Boolean
Whether or not to send the User an activation email.
Only applicable for POSTs and PUTs.

ResetPassword

Boolean

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 default.
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.
IntegrationKey
String
Your unique Integration Key found on the Organization Setup page of the secure website (under My Account)
Required for POST and PUT requests.

 

UserDevice (<UserDevice>)

Field Name
Data Type
Description
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 Name
Data Type
Description
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 Name
Data Type
Description
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/user?email=test@somewhere.com&integrationkey=xxxxxxxxxxxx&companyid=1&format=xm

 

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>