Skip to main content

Subscriber Management

  • Updated

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 (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 Header		HTTP Response
Code		Description
 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 Header		HTTP Response
Code		Description
 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

None beyond the standard

 

 

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 Header		HTTP Response
Code		Description
 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 Header		HTTP Response
Code		Description
 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

None beyond the standard

 

Related articles

Comments

0 comments

Please sign in to leave a comment.