Zywave Public Web Services

What are Web Services?

Build a bridge to seamless integration with BrokerageBuilder Web services. This interface will allow you to:

Efficiently and securely move information to and from the BrokerageBuilder.
Get seamless views of data for better business intelligence.
Eliminate extra steps with direct data transfer and sync.

Built on a standard .NET platform, this service can be used within a custom application to call and retrieve data. It is assumed that users of this documentation are familiar with SOAP Web service development. Please note, that all examples are provided in C# .NET.

BrokerageBuilder Data	Read	Add	Update	Delete
Broker Contacts	X
Accounts	X	X	X	X
Account Contacts	X	X	X	X
Plans	X	X	X
Plan Rates	X	X	X
Plan Benefit Items	X	X	X
Carriers	X
Carrier Commission Schedule	X
Commission Statements	X	X	X
Expected Commissions	X
Actual Commissions	X	X	X	X
Override Commissions	X	X	X	X
Commission Splits	X	X	X	X
Account Activities	X	X	X	X
Carrier Activities	X	X	X	X
Basic Activities	X	X	X	X

How do I get Started?

Setup begins with you. We provide your connection to the data – you set up the bridge.

Industry-standard SOAP protocol accessible by any platform or programming language.
Top security with SSL transport layer and client-based certificates for authorization.
All available functions documented with sample C# code for Microsoft® .NET.

Using the Web Services

To use the public Web services, you should be able to easily and quickly add a connection to the Web services within your application. Because the public Web services are implemented as standard .NET WCF services, it should be a simple setup process for those who use Visual Studio .NET or another developer toolkit with built-in support for Web services and SOAP messaging.

Connecting and Authenticating to the Web Services

To establish a direct and secure connection with Zywave Public Web Services, you must first authenticate your credentials. Begin by contacting Zywave Partner Support at 1.866.499.9283 to request your security certificate. Within 24 hours, you will receive a .pfx file that contains your credentials. To authenticate with your security certificate, save the file locally then load it to your service client. Continue by setting your password within the code in order to successfully load your certificate prior to calling the services. Once security is added to the service client it is applied to all calls made with it; however, if security is not applied you will receive a client certificate error asking you to specify your client credentials.

Adding a Service Reference

To discover, validate, and use the public Web services, you must first add a reference to the endpoint URL. While adding a service reference is dependent on the development tool you use, there should be a relatively simple method to point to the location of the Web service. For instance, in Visual Studio .NET you can use the “Add Service Reference” option. Once pointed at the Web service, additional files needed for your application to interact with Web services should be auto-generated:

Proxy class for the Web service.
Web service description language (.wsdl) file.
Web service discovery files (.disco, .discomap).

Note: Refer to the documentation specific to the development tool you use for instruction on how to add a reference to the Web service.

Using the 'Validate Only' Option

To have the Web services validate a service call without actually saving the information use this option. For instance, before creating an account you are able to see how the system would respond without actually creating the account. This validation aids in your workflow enabling you to confirm whether code would succeed before creation.

If the code succeeds the account will not be created but this process will allow you to verify it is correct.
If the code fails, this process will display the errors (e.g., no product type, conflicting account name, etc.) that must be corrected before a successful account add.

Example: When creating an account you may want to see if this account name exists. To do this you can call CreateAccountWithOptions and ValidateOnly = True.

Result: If no errors, no duplicate account name. If an error occurs, validate whether there is a duplicate account name by reviewing the listed errors.

Using the 'Force' Option

If a warning is thrown by the service, you are able to create your own workaround per se. Simply create an override (e.g., a force option) that will bypass any warning and force a given value to be entered into the system. For instance, do this when you have a duplicate account name that you would like to ignore.

Example: When creating an account you may not mind if there are duplicate account names when creating a new account. If this is the case, call CreateAccountWithOptions with Force = True. This will force the account into the system even if there is already an account with the same name.

Result: Forces value rather than throwing an error. Truncates if entry is over maximum number of characters.

Troubleshooting

The following table lists the basic types of exceptions the public Web service throw and how you can handle them.

Type of Exception	Description
InvalidArgumentFault	Thrown when a method is invoked and at least one of the passed arguments does not meet the parameter specification of the called method.
SecurityNegotiationException	Thrown when a method is invoked and an error occurs while processing security tokens.
ValidationFault	Thrown when a method is invoked and at least one of the passed arguments is invalid.
OperationFailedFault	Thrown when a method is invoked and at least one exception is unhandled.

Using a Catch Block to Retrieve Error Information From a Validation Fault

catch (Exception exc)
{
System.ServiceModel.FaultException<AccountServiceReference.ValidationFault> validationFault = (System.ServiceModel.FaultException<AccountServiceReference.ValidationFault>)exc;            
foreach(AccountServiceReference.ValidationError error in validationFault.Detail.Errors)
       {
      MessageBox.Show(error.Field + ": " + error.Message);                
       }
       MessageBox.Show(exc.ToString());
       }

Sample Service Calls in C# .NET

try
    {
    
        // Instantiate the .NET generated client proxy for the account service
        AccountsV1ServiceReference.AccountServiceClient accountServiceClient =
            new AccountsV1ServiceReference.AccountServiceClient();
    
        // ============
        // Authenticate
        // ============
    
        // After instantiating the client proxy, it will be necessary to assign
        // a client certificate to the proxy which will be used by the public web services
        // to authenticate the service calls. You will need to contact your Zywave
        // representative to obtain the security certificate and password that you will use 
        // to access the public web services. In this sample, we have a client certificate file 
        // named: "ExampleSecurityCertificate.pfx" which has the password: "password"
        // Note: X509Certificate2 is located in the System.Security.Cryptography.X509Certificates
        // namespace.
        if (accountServiceClient.ClientCredentials != null)
        {
            accountServiceClient.ClientCredentials.SupportInteractive = false;
            
            // There are multiple options available for assigning the client certificate
            // to the proxy, 3 examples are provided here:
            
            // Example 1: The security certificate file is stored at C:\ExampleSecurityCertificate.pfx
            // and the certificate is being loaded from that file location at runtime.
            X509Certificate2 certificateFromFile = new X509Certificate2(@"C:\ExampleSecurityCertificate.pfx", "password");
            accountServiceClient.ClientCredentials.ClientCertificate.Certificate = certificateFromFile;
                                
            // Example 2: The security certificate was added to the project as a resource contained in
            // the resource file "Properties\Resources.resx" with the resource name "ExampleSecurityCertificate"
            //X509Certificate2 certificateFromResource = new X509Certificate2(Properties.Resources.ExampleSecurityCertificate, "password");
            //accountServiceClient.ClientCredentials.ClientCertificate.Certificate = certificateFromResource;
    
            // Example 3: The security certificate was installed to the machine's certificate store,
            // and in this example, under the Current User's Personal certificates.                    
            //accountServiceClient.ClientCredentials.ClientCertificate.SetCertificate(StoreLocation.CurrentUser, StoreName.My, X509FindType.FindBySubjectName, "security.zywave.com/ClientAuth/7358");
        }
    
        // =================
        // Create an Account
        // =================
    
        // ... Instantiate an account object and populate details required for 
        // ... the account to be created.
        AccountsV1ServiceReference.Account accountToCreate =
            new AccountsV1ServiceReference.Account();
    
        // ... For this example, a unique account name is generated by
        // ... appending a GUID which avoids a validation fault from being
        // ... thrown for duplicate account names.
        accountToCreate.Name = "Test Account " + Guid.NewGuid().ToString();
        accountToCreate.BrokerageBuilderStatus =
            AccountsV1ServiceReference.BrokerageBuilderStatus.Active;
        accountToCreate.ProductType =
            AccountsV1ServiceReference.ProductType.BrokerageBuilder;
    
        // ... Use the .NET client proxy to call the CreateAccount method which retrieves and
        // ... returns the details needed to create an account.
        AccountsV1ServiceReference.Account accountFromCreate =
            accountServiceClient.CreateAccount(accountToCreate);
    
        // =================
        // Get Account by ID
        // =================
    
        // ... The account object returned from using the CreateAccount method has the ID
        // ... of the account that was created.
        int accountId = accountFromCreate.Id;
    
        // ... Use the .NET client proxy to call the GetAccountById method which retrieves and
        // ... returns the details for an account by account ID.
        AccountsV1ServiceReference.Account accountFromGet =
            accountServiceClient.GetAccountById(accountId);
    
        // =================
        // Update an Account
        // =================
    
        // ... Updating an account requires that all of the audit details are identical
        // ... to those in BrokerageBuilder, i.e., LastUpdatedDate. Therefore,
        // ... in this sample it is necessary to use either the accountFromCreate or 
        // ... accountFromGet objects as the basis for the account to update. Both of these
        // ... objects are identical at this point, and both contain the ID and
        // ... LastUpdatedDate values that correspond to the server.                      
        AccountsV1ServiceReference.Account accountToUpdate = accountFromGet;
    
        // ... Update the city on the account
        accountToUpdate.City = "Milwaukee";
    
        // ... Use the .NET client proxy to call the UpdateAccount method with the
        // ... account details to update. The method will return the details of the account
        // ... that was updated.
        AccountsV1ServiceReference.Account accountFromUpdate =
            accountServiceClient.UpdateAccount(accountToUpdate);
    
        // ====================================================
        // Search for an Account Based on Last Updated Date
        // ====================================================

        // ... Instantiate an account search criteria object
        AccountsV1ServiceReference.AccountSearchCriteria accountSearchCriteria =
            new AccountsV1ServiceReference.AccountSearchCriteria();

        // ... Instantiate a DateTimeSearchCriteria object and assign it to the
        // ... LastUpdatedDate property of the account search criteria. The properties
        // ... left null on the account search criteria object will leave those
        // ... property unfiltered in the search results.
        accountSearchCriteria.LastUpdatedDate =
            new AccountsV1ServiceReference.DateTimeSearchCriteria();

        // ... Set the search type for the LastUpdatedDate search criteria to equals. 
        // ... This sample will search for the record that was just updated.
        accountSearchCriteria.LastUpdatedDate.SearchType =
            AccountsV1ServiceReference.ValueSearchType.Equals;

        // ... Set the value of the LastUpdatedDate search criteria to the LastUpdatedDate 
        // ... of the account just updated.
        accountSearchCriteria.LastUpdatedDate.Value = accountFromUpdate.LastUpdatedDate;

        // ... Instantiate a search options object which allows paging options to be set.
        // ... To get all of the pages, start with PageIndex = 0 and loop the call 
        // ... to SearchAccounts() until all pages have been retrieved. Setting
        // ... PageSize = 100 instructs the call to SearchAccounts() to return a maximum
        // ... of 100 accounts per page.
        AccountsV1ServiceReference.SearchOptions searchOptions =
            new AccountsV1ServiceReference.SearchOptions()
            {
                PageIndex = 0,
                PageSize = 100
            };

        // ... Instantiate an empty list of accounts which will hold all of the account
        // ... search results as each page is retrieved.
        List<AccountsV1ServiceReference.Account> allAccountsFromSearch =
            new List<AccountsV1ServiceReference.Account>();

        bool hasMoreResults = true;
        while (hasMoreResults)
        {
            // ... Use the .NET client proxy to call the SearchAccounts method with the
            // ... account search criteria and search options.
            AccountsV1ServiceReference.PagedItemCollectionOfAccountJA5_SAgdt searchResults =
                accountServiceClient.SearchAccounts(accountSearchCriteria, searchOptions);

            // ... Append the search results for the current page to the list of 
            // ... all accounts
            allAccountsFromSearch.AddRange(searchResults.Results);

            // ... The search results have a property called HasMoreResults which equals
            // ... true until the last page of results is returned
            hasMoreResults = searchResults.HasMoreResults;
                    
            // ... Increment the page index on the search options so that SearchAccounts()
            // ... returns the next page in the next loop iteration
            searchOptions.PageIndex++;
        }
                
        // ... Loop the search results and display the accountID, Name, and LastUpdatedDate.
        foreach (AccountsV1ServiceReference.Account account in allAccountsFromSearch)
        {
            Console.WriteLine("Id: " + account.Id.ToString() + "\n" +
                "Name: " + account.Name + "\n" +
                "LastUpdatedDate: " + account.LastUpdatedDate.ToString());
        }
        // =================
        // Delete an Account
        // =================
    
        // ... Use the .NET client proxy to call the DeleteAccount method with the 
        // ... account ID. This method will not return any details.
        accountServiceClient.DeleteAccount(accountId);
    
        // ===========================
        // Generate a Validation Error
        // ===========================
    
        // ... Attempt to call the UpdateAccount method with the same account object that was
        // ... used previously. Since the LastUpdatedDate is not in sync with the server,
        // ... a validation error will be thrown.
        accountServiceClient.UpdateAccount(accountToUpdate);
    
    }
    catch (System.ServiceModel.FaultException<AccountsV1ServiceReference.ValidationFault> exc)
    {
        // Catch the validation errors that are thrown for any invalid service call
        // parameters.
        foreach (AccountsV1ServiceReference.ValidationError validationError in exc.Detail.Errors)
        {
            // Each validation error will contain an error type (error or warning), the
            // object and field that the error is associated with, and a message describing
            // the violation.
            MessageBox.Show("Error type: " + validationError.ErrorType.ToString() + "\n" +
                "Object name: " + validationError.ObjectName + "\n" +
                "Field: " + validationError.Field + "\n" +
                "Message: " + validationError.Message);
        }
    }

BrokerageBuilder Web Services Documentation

Account Services

Broker Services

Carrier Services

Commission Services

Plan Services

Activity Services