Understanding Action's Parameters

The power of these features is harnessed through the following API call parameters:

  • Common Parameters:
    • Parameter ‘fields
    • Parameter ‘filter
    • Parameter ‘sort
    • Parameters ‘limit‘ and ‘page‘
    • Parameters ‘id‘ and ‘ids‘
    • Parameters ‘key‘ and ‘display‘
    • Parameter ‘model_data‘
    • Parameter ‘related_entities‘
    • Parameter ‘term‘

Parameter ‘fields’

For those familiar with SQL, a field parameter is analogous to a SELECT statement, which is how you define the data you want returned for the entity. This parameter is also the mechanism by which you can get related data about an entity without having to do a secondary API call.

The fields parameter accepts a comma-separated value (CSV) list or array of field names to include, which can be the fields of the entity or related entity and/or their fields. The following examples demonstrate how to use the fields parameter in your API calls.

Parameter &fields is available for actions:

  • find.json
  • find_by_ids.json
  • get.json



Assume you’re working with the /advertiser/campaigns entity:

Example 1 – Getting a subset of entity fields parameters

To limit the result to only return specific fields then set the fields parameter to a comma separated array of the specific fields you’d like returned.


When the API includes the above, it would return results below:

  advertiser_id: 3



Example 2  Include subset of related entity fields

To include only a subset of related entity fields, simply include the specific fields after the related entity name separated by a period.


In addition to the entities fields specified, this parameter also returns the two fields of the related advertiser entity.

  advertiser: {

Parameter ‘filter’

For those familiar with SQL, a filter parameter is analagous to a WHERE clause.

Parameter &filter is available for actions:

  • choices.json
  • count.json
  • find.json



Filter Fields
You can include fields to filter for both the entity that you’re working on, as well as its related entities (similar to the fields parameter).

Comparison Operators
Support comparison operators:

  • =
  • >
  • >=
  • <
  • <=
  • IN
  • LIKE

Multiple Filters
You can combine filters using the AND and OR operators.

Assume you’re working with the /advertiser/campaigns entity:


Example 1 – Field equals value

To filter where a field equals a value set the filter parameter accordingly. Note that the operator = needs to be URL encoded.

filter=(status = ‘active’)

This parameter returns only the campaigns where the status field is active.


Example 2 – Related entity field equals value

You can use related entities as the filter field by referencing them appropriately.

filter=(publisher.name = ‘Ad Network 123′)

This parameter returns the campaigns where the related publisher has a name of Ad Network 123.


Example 3 – Using IN and AND

You can use the in operate like a select statement and include a comma separated array in ( ).

filter=(publisher_id in (1,2,3,4)) AND (status = ‘active’)

This parameter returns the campaigns where both the publisher_id = 1,2,3, or 4 AND status of the publishers is active.

Parameter ‘sort’

The sort parameter determines the order in which results are returned.

Parameter sort is available for actions:

  • choices.json
  • find.json



The examples below assume you’re working with the advertiser/campaigns entity.

Example 1 – single field sort

To sort by a single field simply include the field for the sort parameter. This sorts ascending.


This parameter returns the campaigns by campaign name in alphabetical order (from A to Z).


Example 2 – Single field descending (aka reverse) sort

To sort descending include a colon followed by “desc” after the sort field.


This parameter returns the campaigns by campaign name in reverse alphabetical order (from Z to A).


Example 3 – Multi field sort

You can sort by multiple fields by including them in a comma separated array.


This parameter returns the campaigns by advertiser id (name) in reverse alphabetical order (from Z to A).

Parameters ‘limit’ and ‘page’ for Pagination

This parameter restricts the number of results to send back. Default value is 10.

Pagination parameters limit and page are available with these actions:



Parameters ‘id’ and ‘ids’ for Record Identification

Parameter &id is used by these actions and must reference an identifier of an existing record:

  • delete.json
  • get.json


Parameter &ids is used by this action and must reference an identifier of an existing record:

  • find_by_ids.json



Parameters ‘key’ and ‘display’ for Choices



Parameter ‘model_data’ for Actions ‘save’ and ‘validate’

Parameter ‘data’ is associated with type ‘model_data’.



Parameter ‘related_entities’



Parameter ‘term’ for Autocomplete

Parameter ‘term’ used with Action ‘autocomplete’ searches for a match within values of its Endpoint’s auto-completion column that starts with provided string of characters, case insensitive. Typical fields assigned to auto-completion column are:

  • ‘name’
  • ’email’
  • ‘value’



Have a Question? Please contact support@branch.io for technical support.