Open topic with navigation

XML Customer Service

The XML Customer Service web service provides several web methods for interacting with customers. For Instant SOLO Server Shared URL, this can be reached at https://secure.softwarekey.com/solo/webservices/XmlCustomerService.asmx. If you are using Instant SOLO Server Custom Shared URL or Instant SOLO Server Dedicated URL, replace secure.softwarekey.com with your sub-domain/domain. If you are running a standalone version of SOLO Server, replace secure.softwarekey.com/solo in the URL with the path to your SOLO Server instance. Please contact us if you need assistance determining the correct URL.

All web methods in this service use xml for both input and output. This allows new input and output values to be added without breaking backwards compatibility with existing implementations using the service.

Important

If your integration with the web service validates the xml returned by the web methods, be sure to account for the possibility of new elements being returned in the result. This can easily be done by applying an xslt transform to the result xml to filter out any new fields and then validating the transformed xml.

The XmlCustomerService.asmx web service offers the following webmethods:

GetCustomerDataByAuthor/GetCustomerDataByAuthorS

Used to retrieve author specific customer contact details as well as license information for a customer. This method requires passing in a SOLO Server AuthorID/UserID/Password, but the user does not need any specific permissions. GetCustomerDataByAuthor accepts an XmlDocument input parameter, while GetCustomerDataByAuthorS accepts a string input parameter for the xml so that it is accessible via http post.

Important

Since this web method requires providing an AuthorID, UserID, and User Password as inputs, it should be used for internal applications only and should not be called by client applications distributed to customers. Using this web method in a client application exposes a security risk as this would require including SOLO Server login credentials in the distributed product.

Input

The values of these elements are as follows:

Parameter Data Type Required/Optional Description
AuthorID int Required SOLO Server Author ID.
UserID string Required The User ID of the user from the given author using the service.
UserPassword string Required The password for the User ID.
CustomerID int Optional - Either CustomerID or LicenseID must be provided The Customer ID to retrieve data for.
LicenseID int Optional - Either CustomerID or LicenseID must be provided The LicenseID to retrieve customer data for.

The input xml is in the following format:

XML
<GetCustomerDataByAuthor xmlns="">
    <AuthorID></AuthorID>
    <UserID></UserID>
    <UserPassword></UserPassword>
    <CustomerID></CustomerID>
    <LicenseID></LicenseID>
</GetCustomerDataByAuthor>

Output

The result is returned as XML in the following format:

XML
<?xml version="1.0" encoding="utf-8"?>
<CustomerData>
    <Customer>
        <CompanyName></CompanyName>
        <FirstName></FirstName>
        <LastName></LastName>
        <Address1></Address1>
        <Address2></Address2>
        <City></City>
        <StateProvince></StateProvince>
        <PostalCode></PostalCode>
        <Country></Country>
        <Phone></Phone>
        <Fax></Fax>
        <ExternalReference></ExternalReference>
        <Email></Email>
        <Unregistered></Unregistered>
        <Enabled></Enabled>
        <InvalidAddress></InvalidAddress>
        <Taxable></Taxable>
        <ExcludeFromAll></ExcludeFromAll>
        <IsDistributor></IsDistributor>
        <OfferProduct></OfferProduct>
        <OfferPartners></OfferPartners>
        <Notes></Notes>
        <Password></Password>
    </Customer>
    <License>
        <LicenseID></LicenseID>
        <ActivationPassword></ActivationPassword>
        <EnteredDate></EnteredDate>
        <Status></Status>
        <ExpirationDate></ExpirationDate>
        <Quantity></Quantity>
        <RemainingActivations></RemainingActivations>
        <RemainingDeactivations></RemainingDeactivations>
        <LicenseUpdate></LicenseUpdate>
        <LicenseCounter></LicenseCounter>
        <PaymentPlanInstanceID></PaymentPlanInstanceID>
        <ProductID></ProductID>
        <ProductName></ProductName>
        <ProdOptionID></ProdOptionID>
        <OptionName></OptionName>
    </License>
</CustomerData>

If an error occurs, only the ResultCode and ErrorMessage elements will be returned, otherwise the Customer and License elements will be returned. In the case of an error, the ResultCode will contain one of the following error values:

Parameter Data Type Description
ResultCode int May contain one of the following values, each of which indicates a possible result:
  • -1 - Invalid Login
  • -2 - Invalid XML Document
  • 100 - Invalid Customer ID
  • 101 - Invalid LicenseID
  • 102 - Missing CustomerID/LicenseID
ErrorMessage string Detailed error message for the result code. Only returned in error conditions (a non-zero result code)
Customer Xml Customer details. See the sample XML above for details on the child elements. Note that the Password will be returned as SECURED if it was chosen by the customer and the user account used for authentication does not have View Password permission.
License Xml License details. See the sample XML above for details on the child elements.

CustomerSearch/CustomerSearchS

Used to search for customer details. This method requires passing in a SOLO Server AuthorID/UserID/Password, but the user does not need any specific permissions. CustomerSearch accepts an XmlDocument input parameter, while CustomerSearchS accepts a string input parameter for the xml so that it is accessible via http post.

Important

Since this web method requires providing an AuthorID, UserID, and User Password as inputs, it should be used for internal applications only and should not be called by client applications distributed to customers. Using this web method in a client application exposes a security risk as this would require including SOLO Server login credentials in the distributed product.

Input

The values of these elements are as follows:

Parameter Data Type Required/Optional Description
AuthorID int Required SOLO Server Author ID.
UserID string Required The User ID of the user from the given author using the service.
UserPassword string Required The password for the User ID.
Global bool Optional Whether to perform a global search or just a search against the specified author. Only applicable if the user account has global access permission.
SearchField string Required The search field(s). You can pass one or more search fields in the input to search on a combination of fields. The following search fields are available:
  • CustPass - Customer password. Note that searching on this field will only return results for customer accounts where the password was not set by the customer if the user does not have View Password permission.
  • CompanyName
  • FirstName
  • LastName
  • Address
  • City
  • StateProvince
  • PostalCode
  • Country
  • Email
  • Phone
  • Fax
  • ExternalReference
As an example, to search for John Doe, pass the following in the XML <FirstName>John</FirstName><LastName>Doe</LastName>. By default, these searches uses wildcard matching on both the beginning and end of the search string, meaning that similar results will be returned along with exact matches. You can override this default behavior in 3 ways:
  • Disable this by prepending the escape sequence "-%" (without the quotes) to the beginning of the search string. For example, to perform an exact match search on the email address test@test.com, pass in a value of "-%test@test.com" (without quotes).
  • Override this by specifying only leading or trailing wildcard matches. To override this, include a "%" character on the end of the string you want wildcard matching to take place for. For example, to search on customers with @test.com email addresses, pass in a value of %@test.com.

The input xml is in the following format:

XML
<CustomerSearch xmlns="">
<AuthorID></AuthorID>
<UserID></UserID>
<UserPassword></UserPassword>
<Global></Global>
<SearchField></SearchField>
<SearchField></SearchField>
<!-- ...additional SearchField elements -->
</CustomerSearch>

Output

The result is returned as XML in the following format:

XML
<?xml version="1.0" encoding="utf-8"?>
<Customers>
<ResultCode></ResultCode>
<ErrorMessage></ErrorMessage>
<Customer>
<CustomerID></CustomerID>
<Password></Password>
<CompanyName></CompanyName>
<ContactName></ContactName>
<FirstName></FirstName>
<LastName></LastName>
<MailAddr1></MailAddr1>
<MailAddr2></MailAddr2>
<City></City>
<StateProvince></StateProvince>
<PostalCode></PostalCode>
<Country></Country>
<EMail></EMail>
<Voice></Voice>
<Fax></Fax>
<OfferProduct></OfferProduct>
<OfferPartners></OfferPartners>
</Customer>
<!-- ...additional Customer elements when multiple matches found -->
</Customers>

If an error occurs, only the ResultCode and ErrorMessage elements will be returned, otherwise the Customer elements will be returned if any matches are found. In the case of an error, the ResultCode will contain one of the following error values:

Parameter Data Type Description
ResultCode int May contain one of the following values, each of which indicates a possible result:
  • -1 - Invalid User Login
  • -2 - Invalid XML Document
  • 100 - Invalid Input
ErrorMessage string Detailed error message for the result code. Only returned in error conditions (a non-zero result code)
Customer Xml The following XML tages will be returned:
<CustomerID></CustomerID>
<Password></Password>
<CompanyName></CompanyName>
<ContactName></ContactName>
<FirstName></FirstName>
<LastName></LastName>
<MailAddr1></MailAddr1>
<MailAddr2></MailAddr2>
<City></City>
<StateProvince></StateProvince>
<PostalCode></PostalCode>
<Country></Country>
<EMail></EMail>
<Voice></Voice>
<Fax></Fax>
<OfferProduct></OfferProduct>
<OfferPartners></OfferPartners>

Note that the Password element will be returned as SECURE for for customer accounts where the password was set by the customer if the user does not have View Password permission.

CustomerLogin/CustomerLoginS

Used to verify customer login details. This method requires passing in a SOLO Server AuthorID/UserID/Password, but the user does not need any specific permissions. CustomerLogin accepts an XmlDocument input parameter, while CustomerSearchS accepts a string input parameter for the xml so that it is accessible via http post.

Important

Since this web method requires providing an AuthorID, UserID, and User Password as inputs, it should be used for internal applications only and should not be called by client applications distributed to customers. Using this web method in a client application exposes a security risk as this would require including SOLO Server login credentials in the distributed product.

Input

The values of these elements are as follows:

Parameter Data Type Required/Optional Description
AuthorID int Required SOLO Server Author ID.
UserID string Required The User ID of the user from the given author using the service.
UserPassword string Required The password for the User ID.
Email string Optional Customer email address
CustomerID int Optional The Customer ID, which uniquely identifies the customer to which this License ID belongs.
LicenseID int Optional The License ID.
InvoiceNo int Optional Invoice Number
Password string Required unless performing a login by LicenseID/ActivationPassword The customer password.
ActivationPassword string Required if performing a login by LicenseID/ActivationPassword The license Activation Password. Only supported for use in conjunction with a LicenseID.

The input xml is in the following format:

XML
<CustomerSearch xmlns="">
<AuthorID></AuthorID>
<UserID></UserID>
<UserPassword></UserPassword>
<Email></Email>
<CustomerID></CustomerID>
<LicenseID></LicenseID>
<InvoiceNo></InvoiceNo>
<Password></Password>
<ActivationPassword></ActivationPassword>
</CustomerSearch>

Note that only one of the Email, CustomerID, LicenseID, InvoiceNo, or Nickname elements is required when attempting a login using the customer Password, and ActivationPassword is only supported when attempting a login using LicenseID.

Output

The result is returned as XML in the following format:

XML
<?xmlversion="1.0" encoding="utf-8"?>
<LoginResult>
<ResultCode></ResultCode>
<CustomerID></CustomerID>
<ErrorMessage></ErrorMessage>
</LoginResult>

The ResultCode can take the following values:

Parameter Data Type Description
ResultCode int May contain one of the following values, each of which indicates a possible result:
  • 0 - Success
  • -1 - Invalid User Login
  • -2 - Invalid XML Document
  • 100 - Invalid Input
  • 200 - Invalid Customer Login
CustomerID int The Customer ID. Only returned if login is successful (ResultCode 0).
ErrorMessage string Detailed error message for the result code. Only returned in error conditions (a non-zero result code)