Subscriber Management Details
In ProntoForms, subscribers are part of a team, which is analogous to a particular customer account. Teams are comprised of users who have access to use ProntoForms. Users belong to a particular billing method and a team can have multiple billing methods.
Example: Customer ABC will have 5 users and therefore needs to purchase 5 licenses of ProntoForms. All 5 users will be part of 1 team but the team's billing can be organized in several different ways.
- The customer wishes to have all users bill individually to their own phone numbers. Via the Subscriber API, we will create 1 subscriber for each user desired and will set the number of licenses equal to 1 for each.
- The customer wishes to have 3 users billed to phone number 555-555-1234 and 2 users billed to phone number 555-444-9876. Via the Subscriber API, we will create 2 subscribers to represent the 2 billing methods (one for 555-555-1234 and another for 555-444-9876) with a number of licenses equal to 3 and 2 respectively.
- The customer wishes to have all users billed to a single phone number. Via the Subscriber API, we will create 1 subscriber and set the number of licenses equal to the total number of licenses desired for the team (customer).
Note: Subscribers are organized into the same team when they have the same account number. Therefore, account numbers must be unique across different customers for a given Reseller/Carrier.
Phone Numbers
Ensure that phone numbers in the XML and JSON body are in full international format starting with a '+' symbol and including only digits (no spaces, brackets, dashes, etc.)
ex. +18887627472
Phone Numbers in URLs should only include the digits following the '+' symbol from the preceding description.
ex. 18887627472
Subscriber Management Operations
The following API operations are available for the purposes of user management:
- Create a new Subscriber
- Update an existing Subscriber
- Remove an existing Subscriber
- Suspend an existing Subscriber
- Resume a suspended Subscriber
- Fetch Subscriber Details
Create a new Subscriber (POST /subscribers)
Add a new subscriber to the ProntoForms system
URL Structure
partnerapi.prontoforms.com/partnerapi/[version]/subscribers.json
partnerapi.prontoforms.com/partnerapi/[version]/subscribers.xml
Method
POST
Version(s)
1
Request Body
JSON
{ "phoneNumber": "+18887627472", // Phone number of the subscriber to be added to ProntoForms system // Validation - [String] - matches regex: "^\\+((?:[0-9] ?){6,17}) ?x?,? ?([0-9]{0,10})?$" "prontoTeamId": "12123456", // Optional - Identifier for an existing Pronto Trial Team to for the subscriber to join // Validation - [Integer] - 3 to 12 digits "accountNumber": "12345", // Identifier for the user's account (for team grouping in ProntoForms) // Validation - [String] - 255 char max "email": "a@b.com", // subscriber's email address // Validation - [String] - 255 char max - matches regex: "^[-a-zA-Z0-9'._&%+]+@[-a-zA-Z0-9'._&%+]+\\.[a-zA-Z]{2,4}$" "username": "abcuser", // username for subscriber // Validation - [String] - 255 char max "firstName": "First", // Optional // Validation - [String] - 255 char max "lastName": "Last", // Optional // Validation - [String] - 255 char max "role": "ProntoAdmin", // role for the user in ProntoForms system // Validation - [Enumeration] - ProntoMobileOnly, ProntoUser, ProntoAdmin "generatePassword": "true", // Optional (Default: true) - A password will be generated for the user. When true, "password" field is ignored // Validation - [Boolean] - true, false "password": "abc123", // Optional - the user's login password for Web Admin Portal and for mobile device access // Validation - [String] - 255 char max "sendWelcomeEmail": "true", // Optional (Default: true) - A ProntoForms welcome email will be sent to the user's email address // Validation - [Boolean] - true, false "accountState": "Trial", // the ProntoForms account state of the subscriber // Validation - [Enumeration] - Active, Trial "locale": "es", // Name of the subscriber's company // Validation - [String] - Must be a valid Locale string (Locale IDs found here http://docs.oracle.com/javase/1.4.2/docs/guide/intl/locale.doc.html) "companyName": "ABC Corp", // Name of the subscriber's company // Validation - [String] - 255 char max "promoCode": "octoberPromotion", // Optional - identifier for a defined promotion in ProntoForms (in order to seed the new account with pre-created forms) // Validation - [String] - 255 char max "dealerCode": "ABCD123", // Optional - dealer code used to identify the seller/dealer source of the account // Validation - [String] - 255 char max "agentCode": "123456", // Optional - agent code used to identify the agent/sales rep source of the account // Validation - [String] - 255 char max "salesContactName": "John Smith", // contact name of the sales rep in Carrier for this account // Validation - [String] - 255 char max "salesContactIdentifier": "js1234", // Optional - Unique ID of the sales rep in Carrier for this account // Validation - [String] - 255 char max "salesContactPhoneNumber": "+18887627472", // phone number of the sales rep in Carrier for this account // Validation - [String] - matches regex: "^\\+((?:[0-9] ?){6,17}) ?x?,? ?([0-9]{0,10})?$" "salesSegment": "ABC-DEF", // Optional - sales segment of the Carrier's customer account // Validation - [String] - 255 char max "primaryContactName": "Sally Smith", // primary contact name of the customer account // Validation - [String] - 255 char max "primaryContactEmail": "SallySmith@customer.com", // Optional - primary email address of the customer account // Validation - [String] - 255 char max - matches regex: "^[-a-zA-Z0-9'._&%+]+@[-a-zA-Z0-9'._&%+]+\\.[a-zA-Z]{2,4}$" "primaryContactPhoneNumber": "+18887627472", // Optional - primary phone number of the customer account // Validation - [String] - matches regex: "^\\+((?:[0-9] ?){6,17}) ?x?,? ?([0-9]{0,10})?$" "numberOfUserLicenses": "5" // Optional (only when accountState = 'Trial'), number of user licenses this user is billed for (in the billing scheme: 1 phone number to 1 license, please put 1 for all requests) // Validation - [Integer] - 11 digit max - minimum 1 }XML
<createSubscriber> <phoneNumber>+18887627472</phoneNumber> <prontoTeamId>12123456</prontoTeamId> <accountNumber>12345</accountNumber> <email>a@b.com</email> <username>abcuser</username> <firstName>First</firstName> <lastName>Last</lastName> <role>ProntoAdmin</role> <generatePassword>true</generatePassword> <password>abc123</password> <sendWelcomeEmail>true</sendWelcomeEmail> <accountState>Trial</accountState> <locale>es</locale> <companyName>ABC Corp</companyName> <promoCode>octoberPromotion</promoCode> <dealerCode>ABCD123</dealerCode> <agentCode>123456</agentCode> <salesContactName>John Smith</salesContactName> <salesContactIdentifier>js1234</salesContactIdentifier> <salesContactPhoneNumber>+18887627472</salesContactPhoneNumber> <salesSegment>ABC-DEF</salesSegment> <primaryContactName>Sally Smith</primaryContactName> <primaryContactEmail>SallySmith@customer.com</primaryContactEmail> <primaryContactPhoneNumber>+18887627472</primaryContactPhoneNumber> <numberOfUserLicenses>5</numberOfUserLicenses> </createSubscriber>
Response Body
JSON
{ "identifier": "newid" }XML
<createSubscriberResult> <identifier>newid</identifier> </createSubscriberResult>
Sample cURL Commands
curl -v -k -u user:password -X POST --upload-file FILENAME.xml https://partnerapi.prontoforms.com/partnerapi/[version]/subscribers.xml
curl -v -k -u user:password -X POST --upload-file FILENAME.json https://partnerapi.prontoforms.com/partnerapi/[version]/subscribers.json
Error Codes
Error Code
Response HeaderHTTP Response
CodeDescription UsernameExists 409 Username already exists in ProntoForms PhoneNumberExists 409 Phone number already exists in ProntoForms
Update an existing Subscriber (PUT /subscribers/[phone_number])
Update an existing subscriber
URL Structure
partnerapi.prontoforms.com/partnerapi/[version]/subscribers/[phone_number].json
partnerapi.prontoforms.com/partnerapi/[version]/subscribers/[phone_number].xml
Method
PUT
Version(s)
1
Request Body
All fields are optional. Fields not set will keep their current values. To clear a value, send an empty string as the value. (Please see the "Create a new Subscriber" section for a more detailed description of data parameters)
Note: fields listed in the "Create Subscriber" method call but NOT listed here are create-only parameters that may not be updated post creation.
JSON{ "phoneNumber": "+18887627472", "accountNumber ": "12345", "email": "a@b.com", "username": "abcuser", "firstName": "First", "lastName": "Last", "role": "ProntoAdmin", "accountState": "Active", "locale": "es", "companyName": "ABC Corp", "salesContactName": "John Smith", "salesContactIdentifier": "js1234", "salesContactPhoneNumber": "+18887627472", "salesSegment": "ABC-DEF", "primaryContactName": "Sally Smith", "primaryContactEmail": "SallySmith@customer.com", "primaryContactPhoneNumber": "+18887627472", "numberOfUserLicenses": "5" }XML
<updateSubscriber> <phoneNumber>+18887627472</phoneNumber> <accountNumber>12345</accountNumber> <email>a@b.com</email> <username>abcuser</username> <firstName>First</firstName> <lastName>Last</lastName> <role>ProntoAdmin</role> <accountState>Active</accountState> <locale>es</locale> <companyName>ABC Corp</companyName> <salesContactName>John Smith</salesContactName> <salesContactIdentifier>js1234</salesContactIdentifier> <salesContactPhoneNumber>+18887627472</salesContactPhoneNumber> <salesSegment>ABC-DEF</salesSegment> <primaryContactName>Sally Smith</primaryContactName> <primaryContactEmail>SallySmith@customer.com</primaryContactEmail> <primaryContactPhoneNumber>+18887627472</primaryContactPhoneNumber> <numberOfUserLicenses>5</numberOfUserLicenses> </updateSubscriber>
Response Body
None
Sample cURL Commands
curl -v -k -u user:password -X PUT --upload-file FILENAME.xml https://partnerapi.prontoforms.com/partnerapi/[version]/subscribers/[phone_number].xml
curl -v -k -u user:password -X PUT --upload-file FILENAME.json https://partnerapi.prontoforms.com/partnerapi/[version]/subscribers/[phone_number].json
Error Codes
Error Code
Response HeaderHTTP Response
CodeDescription UsernameExists 409 New username provided already exists for another user PhoneNumberExists 409 New Phone number provided already exists for another subscriber
Remove an existing Subscriber (DELETE /subscribers/[phone_number])
Remove an existing subscriber
URL Structure
partnerapi.prontoforms.com/partnerapi/[version]/subscribers/[phone_number].json
partnerapi.prontoforms.com/partnerapi/[version]/subscribers/[phone_number].xml
Method
DELETE
Version(s)
1
Request Body
None
Response Body
None
Sample cURL Commands
curl -v -k -u user:password -X DELETE https://partnerapi.prontoforms.com/partnerapi/[version]/subscribers/[phone_number].xml
curl -v -k -u user:password -X DELETE https://partnerapi.prontoforms.com/partnerapi/[version]/subscribers/[phone_number].json
Error Codes
Suspend an existing subscriber (POST /subscribers/[phone_number]/suspend)
Suspend an existing subscriber
URL Structure
partnerapi.prontoforms.com/partnerapi/[version]/subscribers/[phone_number]/suspend.json
partnerapi.prontoforms.com/partnerapi/[version]/subscribers/[phone_number]/suspend.xml
Method
POST
Version(s)
1
Request Body
None
Response Body
None
Sample cURL Commands
curl -v -k -u user:password -X POST https://partnerapi.prontoforms.com/partnerapi/[version]/subscribers/[phone_number]/suspend.xml
curl -v -k -u user:password -X POST https://partnerapi.prontoforms.com/partnerapi/[version]/subscribers/[phone_number]/suspend.json
Error Codes
Error Code
Response HeaderHTTP Response
CodeDescription InvalidAccountState 409 The subscriber is not in a valid state for suspension (must be in Active state)
Resume a suspended subscriber (POST /subscribers/[phone_number]/resume)
Resume an existing suspended subscriber
URL Structure
partnerapi.prontoforms.com/partnerapi/[version]/subscribers/[phone_number]/resume.json
partnerapi.prontoforms.com/partnerapi/[version]/subscribers/[phone_number]/resume.xml
Method
POST
Version(s)
1
Request Body
None
Response Body
None
Sample cURL Commands
curl -v -k -u user:password -X POST https://partnerapi.prontoforms.com/partnerapi/[version]/subscribers/[phone_number]/resume.xml
curl -v -k -u user:password -X POST https://partnerapi.prontoforms.com/partnerapi/[version]/subscribers/[phone_number]/resume.json
Error Codes
Error Code
Response HeaderHTTP Response
CodeDescription InvalidAccountState 409 The subscriber is not in a valid state for resume (must be in Suspended state)
Fetch subscriber details (GET /subscribers/[phone_number])
Fetch details associated with an existing subscriber
URL Structure
partnerapi.prontoforms.com/partnerapi/[version]/subscribers/[phone_number].json
partnerapi.prontoforms.com/partnerapi/[version]/subscribers/[phone_number].xml
Method
GET
Version(s)
1
Request Body
None
Response Body
JSON
{ "administrator": "18887627472", // Phone Number (only digits) of the subscriber "billingState": "Active", // State of the subscriber (state is superseded when property suspended is true) "suspended": false, // true if the subscriber is currently suspended "numberOfLicenses": 5, // number of licenses purchased for this subscriber "numberOfUsers": 1 // number of users (consumed licenses) configured in ProntoForms for this subscriber }XML
<susbscriber> <administrator>18887627472</administrator> <billingState>Active</billingState> <suspended>false</suspended> <numberOfLicenses>5</numberOfLicenses> <numberOfUsers>1</numberOfUsers> </subscriber>
Sample cURL Commands
curl -v -k -u user:password -X POST https://partnerapi.prontoforms.com/partnerapi/[version]/subscribers/[phone_number].xml
curl -v -k -u user:password -X POST https://partnerapi.prontoforms.com/partnerapi/[version]/subscribers/[phone_number].json
Error Codes
Comments
0 comments
Please sign in to leave a comment.