Upland Service

The Upland service provides an endpoint to update guest account information for merchants using Upland as their SMS provider.

Endpoints

Set User Fields

POST upland/userFields.json

Register and/or update guest account information.

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • subscriberListId (String) – (required) Upland’s unique identifier for the merchant
  • mobilePhone (String) – (required) Mobile phone number for account
  • userFields (Object) – (required) See UserFieldsTypedInput
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
"result": "failure"
JSON Parameters:
 
  • result (String) – (required) failure
  • errorCode (String) – (required) The error code of the failure.
  • errorMessage (String) – (required) The human readable error message of the failure.

JSON Object Reference

UserFieldsTypedInput
JSON Parameters:
 
  • optIn (Boolean) – (optional) Opt-in true indicates the user wishes to receive emails materials from time to time, false means they do not wish to.
  • salutation (List[String]) – (optional) Allowed values are Mr., Ms., Mrs., Dr., and Rev.
  • firstName (List[String]) – (optional) If a value is provided, it must be non-empty and no longer than 30 characters.
  • lastName (List[String]) – (optional) If a value is provided, it must be non-empty and no longer than 30 characters.
  • companyName (List[String]) – (optional) If a value is provided, it must be non-empty and no longer than 50 characters.
  • email (List[String]) – (optional) If a value is provided, it must be non-empty, no longer than 100 characters, and a well formatted email address. [ ] ( ) < > \\ " and control characters are not allowed anywhere in the email address. There must be exactly one @ in a valid email address. The part after the @ must be a series of . separated segments, and cannot be either led by or trailed by a .
  • addressLabel (List[String]) – (optional) If a value is provided, it must be non-empty and no longer than 100 characters.
  • address1 (List[String]) – (optional) If a value is provided, it must be non-empty and no longer than 100 characters.
  • address2 (List[String]) – (optional) If a value is provided, it must be non-empty and no longer than 100 characters.
  • city (List[String]) – (optional) If a value is provided, it must be non-empty and no longer than 50 characters.
  • stateProvince (List[String]) – (optional) If a value is provided, must be a valid two-letter state or province code for the country. If the country is not specified, US is assumed.
  • postalCode (List[String]) – (optional) If a value is provided, must be a valid postal code for the given country and state/province.
  • country (List[String]) – (optional) Allowed values are US and CA
  • phone (List[String]) – (optional) Validated using Phone Number Validation. See Phone Number Validation
  • fax (List[String]) – (optional) If a value is provided, it must be exactly 10 numeric digits.
  • mobilePhone (List[String]) – (optional) Validated using Phone Number Validation. See Phone Number Validation
  • dateOfBirth (List[Date]) – (optional) If a value is provided, the date must be before the date the request is received, and after 1753-01-01
  • anniversaryDate (List[Date]) – (optional) If a value is provided, the date must be before the date the request is received, and after 1753-01-01
  • custom1 (List[String]) – (optional) If a value is provided, it must be non-empty and no longer than 100 characters. For some programs, additional validation may apply to this field.
  • custom2 (List[String]) – (optional) If a value is provided, it must be non-empty and no longer than 100 characters. For some programs, additional validation may apply to this field.
  • custom3 (List[String]) – (optional) If a value is provided, it must be non-empty and no longer than 100 characters. For some programs, additional validation may apply to this field.
  • custom4 (List[String]) – (optional) If a value is provided, it must be non-empty and no longer than 100 characters. For some programs, additional validation may apply to this field.
  • custom5 (List[String]) – (optional) If a value is provided, it must be non-empty and no longer than 100 characters. For some programs, additional validation may apply to this field.
  • custom6 (List[String]) – (optional) If a value is provided, it must be non-empty and no longer than 100 characters. For some programs, additional validation may apply to this field.
  • username (List[String]) – A value must be provided for endpoints that register, and the value must be at least 6 characters, no longer than 60 characters, not having leading or trailing whitespace, and be unique among cardholders of the merchant. Cannot be specified for users that are not yet registered, unless the endpoint is one that performs registration.
  • password (List[String]) – A value must be provided for endpoints that register, and the value must be at least 6 characters. Cannot be specified for users that are not yet registered, unless the endpoint is one that performs registration.
  • textCampaignOptIn (Boolean) – (optional) Opt-in true indicates the user wishes to receive marketing materials from time to time via text message (SMS), false means they do not wish to.
  • emailVerified (Boolean) – (optional) Verified true indicates the user confirmed their request to receive marketing materials from time to time via email, false means the request was not confirmed.
  • smsOptInVerified (Boolean) – (optional) Verified true indicates the user confirmed their request to receive marketing materials from time to time via text message (SMS), false means the request was not confirmed.
  • nickname (List[String]) – (optional) If a value is provided, it must be non-empty and no longer than 30 characters.
  • avatarCode (List[String]) – (optional) If a value is provided, it must be non-empty and no longer than 30 characters.
  • referrerEmail (List[String]) – (optional) If a value is provided, it contains the email address of an existing user who referred this new user and must be no longer than 100 characters. The referrer will not receive their reward if this value is not provided during registration.
  • referralCode (List[String]) – (optional) If a value is provided, it contains the encrypted code of a bulk referral. The referrer will not receive their reward if this value is not provided during registration. Do not provide both referrerEmail and referralCode.

Phone Number Validation

Phone Number validation in UserFieldsTypedInput depends on the country the phone number is from. The country for which validation is applied is derived from the fields for country, stateProvince, postalCode, the existingAddress passed in separately, and then the country that the “Corp” store exists in, in that order.

All phone number validation allows any of the characers “+()./_- ” (that includes a <space> character). These will be stripped out before the next step is applied. Any phone number with any characters other than these that are not numeric will be deemed invalid.

US Phone Numbers:
A US Phone Number is valid if the numeric part is 10 digits and doesn’t begin with a ‘1’ or a ‘0’, or 11 digits and begins with a ‘1’
UK Phone Numbers:
A UK Phone Number is valid if the numeric part begins with a ‘0’ and is either 8, 10, or 11 digits long
Singaporean Phone Numbers:
An SG Phone Number is valid if the numeric part is exactly 8 digits long

Error Codes

The following are the possible codes and messages that can be returned by the Upland Service.

There are other system-level errors which may be returned which are not documented here.

The caller of the endpoint can use the returned message to display to the end user or, if different wording is desired, can provide their own mapping of code to message.

Code Message
system.error Something went wrong
configuration.error Could not find configuration for %s
no user found Could not find user on mid %i and phone number %s
no user found Could not find user on mid %i and username %s
user already exists User with phone number %s already exsists on mid %i
account already registered User with phone number %s already registered on mid %i
email not unique Email address already exists for a user on mid %i