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.

  • 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"}]