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‘

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.

fields=id,name,site_id

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

{
  id:1,
  name:"campaign1",
  advertiser_id: 3
}

Example 2 – Getting all entity fields

To get all entity fields set the value of fields to an asterisk.

fields =*

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

{
  id:1,
  name:"campaign1",
  advertiser_id: 3,
  ...,
  ...,
  ...,
  all fields
}

Example 3 – Include all fields of related entity

To include all fields of a related entity simply include the entity name or include * after entity.

fields =id,name,advertiser

– or –

fields=id,name,advertiser.*

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

{
  id:1,
  name:"campaign1",
  advertiser: {
    id:3,
    name:"advertiser3",
    ...,
    ...,
    all advertiser fields
  }
}

Example 4 – 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.

fields=id,name,advertiser.id,advertiser.name

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

{
  id:1,
  name:"campaign1",
  advertiser: {
    id:3,
    name:"advertiser3"
  }
}

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
• BETWEEN
• 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.

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.

sort=name

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.

sort=name:desc

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.

sort=advertiser_id,name:desc

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

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:

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

Model_data for Actions Save and Validate

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

Related Entities

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’