.. _api-filter-params-choices:

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

.. _21.2|EKB-8538:

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. 

* ``filter_condition``: 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"}]

* ``filter_field`` and ``filter_text``: the parameters are a field with value to filter on
  that is not the ``field`` parameter, for example to list only countries
  with ``emergency_access_prefix:911``:

  ::

    &field=iso_country_code
    &choice_title=country_name
    &filter_condition=equals
    &filter_field=emergency_access_prefix
    &filter_text=911

  returns:

  ::

    choices":[
    {"value":"CAN","title":"Canada"},
    {"value":"USA","title":"United States of America"}]



.. |VOSS Automate| replace:: VOSS Automate
.. |Unified CM| replace:: Unified CM
.. |API Guide| replace:: API Guide