====== ChannelSUITE API Helper Functions ======

the ChannelSUITE API provides some "helper" functions that may be useful in constructing the client side of an interface to ChannelSUITE. Available helper functions include:

===== List Services =====

this family of services returns lists of standard normalized field values useful for constructing HTML form <select> elements that are compatible with your ChannelSUITE database

  * **country list** -- Returns the list of available country codes in your channelSUITE database. The list is returned in the form of an HTML "options" list that can be cut and pasted right into your HTML code. You may choose to edit the list if you only want to service a subset of all countries in your website form. URL: <code>http://<your channelsuite URL>/API/misc/list.cgi?country=1</code> 
  * **state/province list** -- Addresses in certain countries (notably the US, Canada, and Mexico) include a normalized state/province field. The advantage to using normalized data in this field is that it can facilitate certain functions such as location lookups and lead routing. The state/province list service can perform two functions:
    * //when called with no extra parameters//, the SP (state/province) service returns a space-separated list of country codes that have an associated normalized state/province list. If a country of interest does not appear on this list, please contact our tech support department about having support for states or provinces in your country added to your channelSUITE install. URL: <code>http://<your channelsuite URL>/API/misc/list.cgi?sp=1</code>
    * //when called with an extra "countrycode" parameter// (using the normalized country code as returned by the country list or SP services described above), the state/province list service returns the HTML options list of all states or provinces in that country, again suitable for cutting and pasting into an HTML form. URL: <code>http://<your channelsuite URL>/API/misc/list.cgi?sp=1&countrycode=<your country code></code>

Note: you may be tempted to call the list services via ajax to get an up-to-date list on demand. Since we purposefully avoided "polluting" the returned data with extra information, this can be made to work technically. However, the list data does not change frequently, so hardcoding the option lists and doing an occasionally maintenance update may offer a better cost/performance tradeoff (in other words -- doing it the fancy way may not be worth the effort!)