Use the users API endpoint with the POST method to create a user account.
Base URL
https://api.prontoforms.com
Endpoint
URL structure
https://api.prontoforms.com/api/1.1/users
Request parameters
None
Request header
Include the standard authorization header. This includes the username and password, where username is the API Key ID and password is the API Key Secret.
cURL example
curl -v -k -u {username}:{password} -X POST --upload-file {filename}.{extension} https://api.prontoforms.com/api/1.1/users
where username is the API Key ID and password is the API Key Secret. Supported extensions are .xml and .json.
Request body samples
Request body with required objects
When you create a user with only the required objects, the user has a User role by default, and they receive a welcome email with a link to set their own password.
{
"username": "newuser01",
"email": "newuser@email.com"
}
Note:The username must have between 6 and 255 characters. You can use numbers and special characters.
Request body with optional objects
{
"username": "newuser02",
"email": "jdoe@email.com",
"role": "ProntoAdmin",
"firstName": "Jane",
"lastName": "Doe",
"alternateEmail": "alt@email.com",
"companyName": "Test Company",
"address": {
"address1": "111 Street Street",
"address2": "Unit 222",
"city": "Ottawa",
"state": "Ontario",
"country": "CA",
"zipCode": "K1K 1A1"
},
"locale": "en_CA",
"preferredTimeZone": "America/New_York",
"phoneNumber": "+16131112222",
"billingId": "2020202020",
"defaultViewFormSpaceId": "190000000",
"defaultViewFormDashboardId": "140000000",
"sendWelcomeEmail": false,
"password": "Password123",
"groupIds": ["2100000000", "2100000001"],
"linkToDefaultGroups": true,
"ssoOnly": false
}
Description of objects
This list includes a description of some of the optional objects.
role
- Default:
ProntoUser
- Alternative:
ProntoAdmin
,ProntoMobileOnly
. billingId
- Default: The system adds the user to your main subscription.
- Alternative: Include the Billing ID of the subscription you want to add the user to. Use this object when you have more than one subscription in your account.
defaultViewFormSpaceId
- Default: None
- Alternative: Include the FormSpace ID of the default FormSpace in the user’s account. The user can later change this if they have access to more than one FormSpace.
defaultViewFormDashboardId
- Default: None
- Alternative: Form ID of the default Form that the user can see in the Basic Analytics section.
- Note:You must configure Basic Analytics for the selected form.
sendWelcomeEmail
- Default:
true
- Alternative:
false
- Include this object to configure whether new users receive a welcome email. The email includes instructions to configure their account, including password information.
- Note:If you select false, you must add the password object.
- Info:The section Request body with a custom welcome message describes how to add a welcome message to the welcome email.
password
- Default: Users can configure their own password by following a link in the welcome email.
- Alternative: Set a password for the user. The user receives the password in the welcome email.
- Note:If you decide not to send a welcome email, you must let the user know their password in a way that complies with your organization’s security policies.
groupIds
- Default: User isn’t assigned to any groups.
- Alternative: Include the Group IDs of the groups you want to assign the user to.
linkToDefaultGroups
- Default:
false
- Alternative:
True
- Include this object to add the user to groups configured to add all new users.
- Note:We recommend that you use either the
groupIds
or thelinkToDefaultGroups
objects. If you don’t include them, the new user won’t have access to any forms. ssoOnly
- Default:
false
- Alternative:
True
- Include this object if you want the new user to sign in using your corporate SSO credentials.
Request body with a custom welcome message
{
"username": "newuser03",
"email": "newuser03@email.com",
"customWelcomeMessage": {
"fromUserId": "130000000",
"fromUsername": "companyadmin",
"fromUserAlias": {
"system": "saml",
"alias": "admin"
},
"message": "Welcome to the company! Please follow the steps in this email to configure your account."
}
}
Include one of the following objects:
fromUserId
- ID of the user who sends the welcome email.
fromUsername
- Username of the user who sends the welcome email.
fromUserAlias
- User alias of the user who sends the welcome email.
Request body with organization details
{
"username": "newuser04",
"email": "newuser04@email.com",
"organization": {
"employeeId": "newemployee",
"managerName": "Jane Doe",
"managerEmailAddress": "jdoe@email.com",
"managerPhoneNumber": "+16132221111",
"company": "Company Co.",
"department": "Sales",
"division": "National",
"region": "Eastern Canada",
"subRegion": "Ontario",
"branch": "Ottawa",
"branchOffice": "Kanata",
"office": "02",
"organizationalUnitName": "Executive",
"organizationalUnitAddress": {
"address1": "123 Street Avenue",
"address2": "Apt 100",
"city": "Ottawa",
"state": "Ontario",
"country": "CA",
"zipCode": "A1B 2C3"
}
}
}
Response code
201—Created
Response example
{ "identifier": "136290000" }
Tip:You can use this ID number to update a user, change a user’s password, or delete a user with the API.
Error codes
Error code | Error message | HTTP response code | Description |
---|---|---|---|
UsernameExists | Username Exists: The username already exists | 409 | The username you selected is not available. Choose a different username. |
InvalidRequestDataFormat | Invalid Request Data: The data you supplied was not formatted correctly, or did not meet all requirements. Please fix your data and try again. | 400 | A welcome email must be sent if the password is to be generated. |
InvalidRequestDataFormat | Invalid Request Data: The data you supplied was not formatted correctly, or did not meet all requirements. Please fix your data and try again. | 400 | Username must be between 6 and 255 characters. |
InvalidIdentifierFormat | Invalid Identifier: The object identifier ‘xxx’ is not valid. | 404 | The format of one of your IDs is not correct. Verify that all your IDs are correct. |
ObjectNotFound | Object Not Found: The object you requested could not be found. | 404 | The system couldn’t find one of the IDs. Verify that all your IDs are correct. |
Comments
0 comments
Please sign in to leave a comment.