Upland Service ============== The Upland service provides an endpoint to update guest account information for merchants using Upland as their SMS provider. .. contents:: Topics Endpoints --------- Set User Fields ~~~~~~~~~~~~~~~~~~~ .. http:post:: upland/userFields.json Register and/or update guest account information. The following authentication methods are allowed for this endpoint: * :ref:`b2b_auth` :jsonparam String subscriberListId: *(required)* Upland's unique identifier for the merchant :jsonparam String mobilePhone: *(required)* Mobile phone number for account :jsonparam Object userFields: *(required)* See :http:jsonentity:`UserFieldsTypedInput` .. http:response:: success :jsonparam String result: *(required)* ``success`` .. http:response:: failure :jsonparam String result: *(required)* ``failure`` :jsonparam String errorCode: *(required)* The error code of the failure. :jsonparam String errorMessage: *(required)* The human readable error message of the failure. JSON Object Reference --------------------- .. http:jsonentity:: UserFieldsTypedInput :jsonparam Boolean optIn: *(optional)* Opt-in ``true`` indicates the user wishes to receive emails materials from time to time, ``false`` means they do not wish to. :jsonparam List[String] salutation: *(optional)* Allowed values are ``Mr.``, ``Ms.``, ``Mrs.``, ``Dr.``, and ``Rev.`` :jsonparam List[String] firstName: *(optional)* If a value is provided, it must be non-empty and no longer than 30 characters. :jsonparam List[String] lastName: *(optional)* If a value is provided, it must be non-empty and no longer than 30 characters. :jsonparam List[String] companyName: *(optional)* If a value is provided, it must be non-empty and no longer than 50 characters. :jsonparam List[String] email: *(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 ``.`` :jsonparam List[String] addressLabel: *(optional)* If a value is provided, it must be non-empty and no longer than 100 characters. :jsonparam List[String] address1: *(optional)* If a value is provided, it must be non-empty and no longer than 100 characters. :jsonparam List[String] address2: *(optional)* If a value is provided, it must be non-empty and no longer than 100 characters. :jsonparam List[String] city: *(optional)* If a value is provided, it must be non-empty and no longer than 50 characters. :jsonparam List[String] stateProvince: *(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. :jsonparam List[String] postalCode: *(optional)* If a value is provided, must be a valid postal code for the given country and state/province. :jsonparam List[String] country: *(optional)* Allowed values are ``US`` and ``CA`` :jsonparam List[String] phone: *(optional)* Validated using Phone Number Validation. See :ref:`phone_validation_upland` :jsonparam List[String] fax: *(optional)* If a value is provided, it must be exactly 10 numeric digits. :jsonparam List[String] mobilePhone: *(optional)* Validated using Phone Number Validation. See :ref:`phone_validation_upland` :jsonparam List[Date] dateOfBirth: *(optional)* If a value is provided, the date must be before the date the request is received, and after 1753-01-01 :jsonparam List[Date] anniversaryDate: *(optional)* If a value is provided, the date must be before the date the request is received, and after 1753-01-01 :jsonparam List[String] custom1: *(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. :jsonparam List[String] custom2: *(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. :jsonparam List[String] custom3: *(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. :jsonparam List[String] custom4: *(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. :jsonparam List[String] custom5: *(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. :jsonparam List[String] custom6: *(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. :jsonparam List[String] username: 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. :jsonparam List[String] password: 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. :jsonparam Boolean textCampaignOptIn: *(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. :jsonparam Boolean emailVerified: *(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. :jsonparam Boolean smsOptInVerified: *(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. :jsonparam List[String] nickname: *(optional)* If a value is provided, it must be non-empty and no longer than 30 characters. :jsonparam List[String] avatarCode: *(optional)* If a value is provided, it must be non-empty and no longer than 30 characters. :jsonparam List[String] referrerEmail: *(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. :jsonparam List[String] referralCode: *(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_validation_upland: 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 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 | +----------------------------------------------------------+------------------------------------------------------------------------+