API: User Management

The following API operations are available for the purposes of user management:

 

Retrieve a List of Users

Use this method to retrieve a list of your users.  Optionally, you may include a filter to narrow the results.  Calling this method will return a paged list of users.  If the number of users exceeds the size of the page, subsequent requests can be made in order to retrieve the full list.

URL Structure

api.prontoforms.com/api/[version]/users.xml
api.prontoforms.com/api/[version]/users.json 

Method

GET

Request Parameters

 Parameter  Required  Default value  Description
 q  no    Query string for filtering.  The filter matches part of the username, email address, first or last name.
 p  no  0  0-based page number.
 s  no  100  Number of results in the page.  The maximum value is 100.

Sample Responses

XML

<pagedList totalNumberOfResults="1">
 <user identifier="13001">
 <username>user@host.com</username>
 <email>user@host.com</email>
 <firstName>Robert</firstName>
 <lastName>Smith</lastName>
 </user>
</pagedList>

JSON

{
"totalNumberOfResults": 1,

"pageData": [{
"identifier": "13001",
"username": "user@host.com",
"email": "user@host.com",
"firstName": "Robert",
"lastName": "Smith"
}]
}

Sample cURL Commands

curl -v -k -u user:password -X GET https://api.prontoforms.com/api/1/users.xml
curl -v -k -u user:password -X GET https://api.prontoforms.com/api/1/users.json

Important Note: Replace user with your API Key ID and password with your API Key secret.

[ top ]

 

Retrieve details of a user

Use these methods to retrieve details of a user.  The user may be identified by their ID or by their username. Click here for more information on finding ID values.

URL Structure

api.prontoforms.com/api/[version]/users/[id].xml
api.prontoforms.com/api/[version]/users/[id].json 
api.prontoforms.com/api/[version]/users/username/[username].xml
api.prontoforms.com/api/[version]/users/username/[username].json

Method

GET

Request Parameters

 Parameter  Required  Default value  Description
 tz  no   UTC  Timezone used to present timestamps.

Sample Responses

XML

<user identifier="13001">
 <username>rsmith</username>
 <role>ProntoAdmin</role>
 <email>rsmith@host.com</email>
 <firstName>Robert</firstName>
 <lastName>Smith</lastName>
<companyName>Test Company</companyName>
<address>
<address1>123 Fake Street</address1>
<address2>Apt 100</address2>
<city>Ottawa</city>
<state>Ontario</state>
<country>CA</country>
<zipCode>A1B 2C3</zipCode>
</address>
<locale>en</locale>
<preferredTimeZone>America/New_York</preferredTimeZone>
<phoneNumber>+16132252255</phoneNumber>
<billingId>2551</billingId>
<defaultViewFormSpaceId>123</defaultViewFormSpaceId>
<defaultViewFormDashboardId>456</defaultViewFormDashboardId>
<groupIds>
<identifier>2101</identifier>
<identifier>2102</identifier>
</groupIds>
</users>

 

JSON

{
"identifier": "13001",
"username": "rsmith",
"role": "ProntoAdmin",
"email": "rsmith@host.com",
"firstName": "Robert",
"lastName": "Smith",
"companyName":"Test Company",
"address":{
"address1":"123 Avenue Street",
"address2":"Apt 100",
"city":"Ottawa",
"state":"Ontario",
"country":"CA",
"zipCode":"A1B 2C3"
},
"locale": "en_CA",
"preferredTimeZone": "America/New_York",
"phoneNumber":"+16132252225,
"billingId": "24001",
"defaultViewFormSpaceId":"123",
"defaultViewFormDasboardId":"456",
"groupIds": ["18001","18002"],
"lastLoginDate": "2012-01-30T18:20:46-08:00"
}

Sample cURL Commands

curl -v -k -u user:password -X GET https://api.prontoforms.com/api/1/users/[id].xml
curl -v -k -u user:password -X GET https://api.prontoforms.com/api/1/users/[id].json
curl -v -k -u user:password -X GET https://api.prontoforms.com/api/1/users/username/[username].xml
curl -v -k -u user:password -X GET https://api.prontoforms.com/api/1/users/username/[username].json 

Important Note: Replace user with your API Key ID and password with your API Key secret.  Also, replace [id] with a user ID.

[ top ]

 

Create a user

Use the information below to create a new user via the API.  See Using POST and PUT for additional information.

URL Structure

api.prontoforms.com/api/[version]/users.xml
api.prontoforms.com/api/[version]/users.json 

Method

POST

Request Parameters

None.

Request Body Samples

XML

<createUser>
 <username>newadmin01</username>  <role>ProntoAdmin</role>         <!-- Optional, defaults to ProntoUser -->
<email>admin@att.com</email>
<alternateEmail>alt@email.com</alternateEmail> <!--Optional-->
 <firstName>Jane</firstName>      <!-- Optional -->
 <lastName>Smith</lastName>       <!-- Optional -->
<companyName>Test Company</companyName> <!--Optional-->
<address> <!--Optional -->
<address1>123 Fake Street</address1>
<address2>Apt 100</address2>
<city>Ottawa</city>
<state>Ontario</state>
<country>CA</country>
<zipCode>A1B 2C3</zipCode>
</address>
<locale>en</locale> <!-- Optional -->
<preferredTimeZone>America/New_York</preferredTimeZone> <!-- Optional -->
<phoneNumber>+16132252255</phoneNumber>
<sendWelcomeEmail>false</sendWelcomeEmail> <!-- Optional, defaults to false-->
<billingId>2551</billingId> <!-- Optional when only 1 billing method on account-->
<defaultViewFormSpaceId>123</defaultViewFormSpaceId> <!-- Optional-->
<defaultViewFormDashboardId>456</defaultViewFormDashboardId> <!-- Optional -->
<password>YfD123!</password> <!-- Optional, defaults to system-generated password sent in email-->
<groupIds> <!-- Optional, but user has no access when not specified -->
<identifier>2101</identifier>
<identifier>2102</identifier>
</groupIds>
</createUser>

JSON

{
"username": "newadmin01",
"email": "jane@host.com",
"role": "ProntoAdmin", // Optional, defaults to ProntoUser
"firstName": "Jane", // Optional
"lastName": "Smith", // Optional "email":"admin@email.com",
"alternateEmail":"alt@email.com", // Optional
"companyName":"Test Company", // Optional
"address":{ // Optional
"address1":"123 Fake Street",
"address2":"Apt 100",
"city":"Ottawa",
"state":"Ontario",
"country":"CA",
"zipCode":"A1B 2C3"
}, "locale": "en_CA", // Optional
"preferredTimeZone": "America/New_York", // Optional
"phoneNumber":"+16132252255", // Optional
"billingId": "26001", // Optional when there is only 1 billing method on the team
"defaultViewFormSpaceId":"123", // Optional
"defaultViewFormDashboardId":"456", // Optional
"sendWelcomeEmail": false, // Optional, defaults to true
"password": "Yf9D!v0%", // Optional, defaults to system-generated password (sent in email)
"groupIds": ["16001","16002"] // Optional, but user has no access when not specified
}

Response Body Samples

XML

<createUserResult> 
 <identifier>13010</identifier>
</createUserResult> 

JSON

{
"identifier": "13010"

Sample cURL Commands

curl -v -k -u user:password -X POST --upload-file FILENAME.xml https://api.prontoforms.com/api/1/users.xml
curl -v -k -u user:password -X POST --upload-file FILENAME.json https://api.prontoforms.com/api/1/users.json

Important Note: Replace user with your API Key ID and password with your API Key secret. Also, replace FILENAME with the name of your actual file which should be formatted as per the XML or JSON request body samples above.

[ top ]

 

Update a User

Use the information below to update an existing user via the API.  See Using POST and PUT for additional information.

URL Structure

api.prontoforms.com/api/[version]/users/[id].xml
api.prontoforms.com/api/[version]/users/[id].json 

Method

PUT

Request Parameters

None.

Request Body Samples

Please note the following when working with this method:

  • All fields are optional
  • Fields not set in the request body will retain existing values
  • To clear the value of a field, send an empty string as the value

XML

<updateUser>
<username>bjohnston</username>
 <email>bjohnston@host.com</email>
 <role>ProntoAdmin</role>
<email>admin@att.com</email>
<alternateEmail>alt@email.com</alternateEmail>
  <firstName>Bethany</firstName>
 <lastName>Johnston</lastName> <companyName>AT&amp;T</companyName>
<address>
<address1>123 Fake Street</address1>
<address2>Apt 100</address2>
<city>Ottawa</city>
<state>Ontario</state>
<country>CA</country>
<zipCode>A1B 2C3</zipCode>
</address>
  <locale>en_CA</locale>
 <preferredTimeZone>America/New_York</preferredTimeZone>   <phoneNumber>+16132252255</phoneNumber>
<billingId>2551</billingId>
<defaultViewFormSpaceId>123</defaultViewFormSpaceId>
<defaultViewFormDashboardId>456</defaultViewFormDashboardId>   <groupIds>
     <identifier>18001</identifier>
  </groupIds>
</updateUser>

JSON

{
"username": "bjohnston",
"role": "ProntoAdmin",
"email":"admin@att.com",
"alternateEmail":"alt@email.com", "firstName": "Bethany",
"lastName": "Johnston", "companyName":"AT&T",
"address":{
"address1":"123 Fake Street",
"address2":"Apt 100",
"city":"Ottawa",
"state":"Ontario",
"country":"CA",
"zipCode":"A1B 2C3"
}, "locale": "en_CA",
"preferredTimeZone": "America/New_York", "phoneNumber":"+16132252255",
"billingId":"2551",
"defaultViewFormSpaceId":"123",
"defaultViewFormDashboardId":"456", "groupIds": ["18001"]
}

Response Body Samples

This method does not send a response body.

Sample cURL Commands

curl -v -k -u user:password -X PUT --upload-file FILENAME.xml https://api.prontoforms.com/api/1/users/[id].xml
curl -v -k -u user:password -X PUT --upload-file FILENAME.json https://api.prontoforms.com/api/1/users/[id].json

Important Note: Replace user with your API Key ID and password with your API Key secret.  Also, replace FILENAME with the name of your actual file which should be formatted as per the XML or JSON request body samples above.  Finally, replace [id] with a user ID.

Error Codes

Error Code
Response Header
HTTP Response
Code
Description
 UsernameExists 409  New username already exists in ProntoForms

[ top ]

 

Update a user password

Use the information below to update the password of an existing user via the API.  See Using POST and PUT for additional information.

URL Structure

api.prontoforms.com/api/[version]/users/[id]/password.xml
api.prontoforms.com/api/[version]/users/[id]/password.json 

Method

POST

Request Parameters

None.

Request Body Samples

XML

<changePassword>
<password>0Pz#2m*P</password>
</changePassword>

JSON

{
"password": "0Pz#2m*P",
}

Response Body Samples

This method does not send a response body.

Sample cURL Commands

curl -v -k -u user:password -X POST --upload-file FILENAME.xml https://api.prontoforms.com/api/1/users/[id]/password.xml
curl -v -k -u user:password -X POST --upload-file FILENAME.json https://api.prontoforms.com/api/1/users/[id]/password.json

Important Note: Replace user with your API Key ID and password with your API Key secret.  Also, replace FILENAME with the name of your actual file which should be formatted as per the XML or JSON request body samples above.  Finally, replace [id] with a user ID.

Error Codes

There are no method-specific errors for this method.
Consult the API Error Handling reference for general information on error handling.

[ top ]

 

Delete a user

Use the following information to permanently delete a user via the API.  
NOTE:   Deleting a user from the system does not delete any data records, forms, or other objects created by that user.

URL Structure

api.prontoforms.com/api/[version]/users/[id].xml
api.prontoforms.com/api/[version]/users/[id].json 

Method

DELETE

Request Parameters

None.

Request Body Samples

This method does not make use of a request body.

Response Body Samples

This method does not send a response body.

Sample cURL Commands

curl -v -k -u user:password -X DELETE https://api.prontoforms.com/api/1/users/[id].xml
curl -v -k -u user:password -X DELETE https://api.prontoforms.com/api/1/users/[id].json

Important Note: Replace user with your API Key ID and password with your API Key secret.  Also, replace [id] with a user ID.

Error Codes

There are no method-specific errors for this method.
Consult the API Error Handling reference for general information on error handling.

[ top ]

Was this article helpful?
1 out of 1 found this helpful
Have more questions? Submit a request

Comments

  • Avatar
    Kyle Ketterer

    I hope the following bit of information will be useful to somebody in the future:

    When sending an XML body to the server, it NEEDS the standard xml header....eg: <?xml version="1.0"?>

    Without this header, the request will fail. Also, the XML example above for updating user passwords appears to be incorrect as the correct XML syntax uses left/right arrows <changePassword>, not brackets [changePassword]

  • Avatar
    Danielle Morley

    Hello Kyle,

    Thank you for your comment.  The [changePassword] vs. <changePassword> issue has been corrected.  As for the standard XML header being required, we have found that this is not the case.  If you are encountering an error and would like assistance, please contact Support at 1-888-762-7472 or support@prontoforms.com with the error message and we would be happy to troubleshoot.  

     

  • Avatar
    Sunil Pai

    I don't see how I can determine the group ids to specify when creating a user.

    Is there a REST API command to retrieve the list of groups?

    Or do I just click on each group in the web UI and note the number in the URL?

  • Avatar
    GlennMC

    @Sunil, currently looking in the web UI is the only method of discovering the groups IDs.

    /Glenn

     

  • Avatar
    Sunil Pai

    In the "Delete a User" section, the URLs in "URL Structure" are for changing a user's password. The URLs listed in "Sample cURL Commands" are correct. Please update the documentation.

  • Avatar
    Danielle Morley

    Sunil,  

    Thank you for bringing this our our attention.  The URLs have been corrected.

  • Avatar
    Manson Rawding

    Hello I am trying to use javascript to pull back and display some JSON data as a quick proof of concept that the REST API works from a web client.  Has anyone ever tried this?  Is this code on the right track?  Has anyone got any samples of how one would use javascript to do this?

    Thanks, I appreciate any help.

     

    <!DOCTYPE html>

     

    <html>

     

    <body>

     

     

     

    <div id="id01"></div>

     

     

     

    <script>

     

    var xmlhttp = new XMLHttpRequest();

     

     

     

    var apiKey = "[Enter your generated API key here]";

     

    var url = "https://api.prontoforms.com/api/1/users.json&key=apiKey";

     

     

     

     

     

    xmlhttp.onreadystatechange = function() {

     

        if (xmlhttp.readyState == 4 && xmlhttp.status == 200) {

     

            var myArr = JSON.parse(xmlhttp.responseText);

     

            myFunction(myArr);

     

        }

     

    };

     

    xmlhttp.open("GET", url, true);

     

    xmlhttp.send();

     

     

     

    function myFunction(arr) {

     

        var out = "";

     

        var i;

     

       for(i = 0; i < arr.length; i++) {

     

            out += '<a href="' + arr[i].url + '">' +

     

            arr[i].display + '</a><br>';

     

        }

     

        document.getElementById("id01").innerHTML = out;

     

    }

     

    </script>

     

     

     

    REST API test:

     

    </body>

     

    </html>

     

  • Avatar
    GlennMC

    @Manson Rawling

    Putting the API credentials as a URL argument in that way is not going to work.  

    Here are a few articles on handling basic authentication (the authentication method through which you need to provide the key and secret) within javascript that may help:

    http://stackoverflow.com/questions/5507234/how-to-use-basic-auth-with-jquery-and-ajax

    http://stackoverflow.com/questions/491914/pure-javascript-code-for-http-basic-authentication

    I hope this helps.

    /Glenn