Filter Parameters for Choices
-----------------------------


For the context in which the filter parameter are used, refer to
the Choices topic on the ``/choices/`` endpoint.

Format:

::

  GET http://<server_address>/api/<resource_type>/<resource_name>/choices/
   ?hierarchy=[hierarchy]
   &format=json
   &<filter_parameters>

Response data of the ``/choices/`` endpoint *without* filter parameters is a list of
value-title pairs of the business keys. This can be modified with filter parameters.


Example without ``<filter_parameters>``:

* Request

  ::
  
    GET http://<server_address>/api/data/Countries/choices/
     ?hierarchy=[hierarchy]
     &format=json

* Response

  ::

     HTTP 200 OK
     Vary: Accept
     X-Request-ID: 9bcd77b4cd27dccd0f18a1d8d22e7ddab85aa848
     Content-Type: text/html; charset=utf-8
     Allow: GET, HEAD, OPTIONS
     Response-Content:
     {
     
         pagination : {
             direction :  asc,
             maximum_limit :  2000,
             skip :  0,
             limit :  0,
             total_limit :  ,
             total :  37
         },
         meta : {
             query :  /api/data/Countries/choices/,
             references : [
                {
                    pkid :  5a16c3c68963f91b84baf357,
                    href :  /api/data/Countries/5a16c3c68963f91b84baf357/
                },
                ...
             ]
         },
         choices : [
             {
                 value :  ["Australia", "AUS", "hcs"],
                 title :  ["Australia", "AUS", "hcs"]
             },
             ...

Filter parameters available to modify the response:

* ``field``: specifies the field in the business key to return as title and value, for example
  adding the parameter below

  ::

     &field=iso_country_code

  would return:

  ::
  
     choices : [
         {
             value :  ["AUS"],
             title :  ["AUS"]
         },
         ...


* ``choice_title``: specifies the field of the business key to be the ``title`` value, for example
  adding the parameter below
  

  ::

     &field=iso_country_code
     &choice_title=country_name
     
  would return:

  ::
   
     choices : [
         {
             value :  ["AUS"],
             title :  ["Australia"]
         },
         ...
 


* ``title``:  specifies the value of the ``field`` parameter to filter on, for example
  adding the parameter below

  ::
  
    &field=iso_country_code
    &title=BHR
    &choice_title=country_name
    
  would return:
  
  ::
  
     choices : [
         {
             value :  ["BHR"],
             title :  ["Bahrain"]
         },
         ...

Note that the ``title`` parameter matches on the *start* of the value. 

For an *exact* match, the ``&filter_condition=equals`` parameter can be added, for example:
 
::

   &filter_condition=equals
   &field=iso_country_code
   &choice_title=country_name
   &title=N

returns no value:
  
::

   choices  []
  

Without ``filter_condition=equals``, in other words, with just:


::

   &field=iso_country_code
   &choice_title=country_name
   &title=N

returns:

::

   choices": [
   {"value": "NLD", "title": "Netherlands"},
   {"value": "NZL", "title": "New Zealand"},]



.. |VOSS-4-UC| replace:: VOSS-4-UC
.. |Unified CM| replace:: Unified CM
.. |API Guide| replace:: API Guide