XML Customer Service

The XML Customer Service web service provides several web methods for interacting with customers.

For SOLO Server Shared URL, this can be reached at https://secure.softwarekey.com/solo/webservices/XmlCustomerService.asmx

• When using SOLO Server Shared / Custom URL, replace secure with your custom subdomain.
• When using SOLO Server Dedicated URL, replace secure.softwarekey.com with your domain.
• When using SOLO Server Self-Hosted, 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.

The XmlCustomerService.asmx web service offers the following web methods:

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/API UserID/API UserPassword, 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.

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 API User ID of the user from the given author using the service (previously the regular User ID). The API User ID and Password need to be used, as support for the regular User ID and Password will be removed in the future.
UserPassword	string	Required	The API User Password for API User ID (previously the regular User Password for the User ID). The API User ID and Password need to be used, as support for the regular User ID and Password will be removed in the future.
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>

<CustomerID></CustomerID>
<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/API UserID/API UserPassword, 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.

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 API User ID of the user from the given author using the service (previously the regular User ID). The API User ID and Password need to be used, as support for the regular User ID and Password will be removed in the future.
UserPassword	string	Required	The API User Password for API User ID (previously the regular User Password for the User ID). The API User ID and Password need to be used, as support for the regular User ID and Password will be removed in the future.
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: 0 - Success -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/API UserID/API UserPassword, 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.

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 API User ID of the user from the given author using the service (previously the regular User ID). The API User ID and Password need to be used, as support for the regular User ID and Password will be removed in the future.
UserPassword	string	Required	The API User Password for API User ID (previously the regular User Password for the User ID). The API User ID and Password need to be used, as support for the regular User ID and Password will be removed in the future.
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)