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 using the REST GET, POST and DELETE verbs:

http://secure.formsfly.com/api/v1/suser?format=[xml|json]

To search for and retrieve multiple Users at once, use a GET with the search API found at:

http://secure.formsfly.com/api/v1/suser/search?format=[xml|json]

The format query string parameter controls the desired response format.  Specify either xml or json.

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.
ProviderId Integer Yes Your unique Provider Id found on the Organisation Setup page of the secure website (under Your Account)
Integrationkey String Yes Your unique Integration Key found on the Organisation Setup page of the secure website (under Your Account)
Id
or
Email
or
ExternalId
GUID

string

string

Yes The unique identifier of the User you wish to retrieve
or
The email address of the User to retrieve
or
The external identifier for the User to retrieve

GET Response

The data returned from a SUser GET is provided as follows:

SUser Response (<SUserResponse>)

Field Name Data Type Description
SUser SUser The returned SUser STask object
ResponseStatus ResponseStatus Details of any errors that may have occurred

SUser (<SUser>)

Field Name Data Type Description
Id GUID Unique identifier of the User.
ProviderId Integer Your unique Provider Id found on the Organisation 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
SUserDevices SUserDevices List of SUserDevice – 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
IntegrationKey String Your unique Integration Key found on the Organisation Setup page of the secure website (under Your Account)
Required for POST and PUT requests.

SUserDevice (<SUserDevice>)

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

http://secure.formsfly.com/api/v1/suser? email=test@somewhere.com& integrationkey=xxxxxxxxxxxx&providerid=1&format=xml

XML Response

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: length
<SUserResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.servicestack.net/types">   <ResponseStatus>     <ErrorCode>String</ErrorCode>     <Message>String</Message>     <StackTrace>String</StackTrace>     <Errors>       <ResponseError>         <ErrorCode>String</ErrorCode>         <FieldName>String</FieldName>         <Message>String</Message>       </ResponseError>     </Errors>   </ResponseStatus>   <SUser>     <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>     <ProviderId>0</ProviderId>     <SUserDevices>       <SUserDevice>         <Hardware>String</Hardware>         <Id>00000000-0000-0000-0000-000000000000</Id>         <OS>String</OS>         <OSVersion>String</OSVersion>       </SUserDevice>     </SUserDevices>     <Status>String</Status>     <WebsiteRole>String</WebsiteRole>   </SUser> </SUserResponse>
API – DELETE User. Will it connect to our existing systems?. API FormsFly System. Advanced Integration. API – POST Form Entry to External Web Service. API – DELETE Task. API – GET Tasks. Integration API Overview. API – PUT User. REST Connector. API – POST User. API – Form GET Media File. API – POST Task. API – Form GET Entries. API – GET Data Source. API – GET Users. API – PUT Data Source.