Primitives
Primitive parameter data types such as integer, string, boolean, and double, are passed to the API as simple name/value pairs.
For example, passing an integer value of (5) for a parameter named "foo" would be achieved by including the following in the API call:
&foo=5
* NOTE: in order to pass boolean values you should use 0 to indicate false and 1 to indicate true. Do not pass the strings "true" or "false".
Arrays
Array parameters are passed to the API with a format used by PHP and other common web scripting languages, utilizing a "[]" notation after each instance of the parameter name to indicate that it should be parsed as an array.
For example, passing an array of integers (1, 2, 5) for a parameter named "foo" would be achieved by including the following in the API call:
&foo[]=1&foo[]=2&foo[]=5
* NOTE: Arrays of type "mixed" do not enforce the data type of the array values. This indicates that the parameter can accept strings or numbers.
Structured Objects
A Structured Object parameter type is used to provide multiple key/value pairs. The structure is identical to that of the "Data Object" type parameter except it is not bound to a Model.
For example, an API method that has a "Structured Object" parameter named "options" that is used to specify a couple of configurations ("name" and "frequency") could be called in the following way:
&options[name]=test&options[frequency]=weekly
An array of Structured Objects
An Array of Structured Object parameter types is used to provide a series of objects, each with multiple key/value pairs. The structure is identical to that of the "Structured Object" type parameter except that it supports passing multiple instances of the structured object for a single parameter.
For example, an API method that has an "Array of Structured Object" parameter named "daterange" is used to specify multiple date ranges, each with a "start" and an "end" field that is a date. To specify two ranges (2011-05-01 to 2011-06-02) and (2014-01-01 to 2014-02-01) the parameter would be formatted as follows:
&daterange[0][start]=2011-05-01&daterange[0][end]=2011-06-02&daterange[1][start]=2014-01-01&daterange[1][end]=2014-02-01
Notice that the parameters of each object in the array are grouped together using the 0-based array index in the example above. The first object has an index of "0" and the second object has an index of "1". To add more objects the index would be incremented.
Unstructured Objects
An Unstructured Object parameter type is used to provide multiple key/value pairs. It is identical to the
"Structured Object" parameter type, except that the keys are not predefined.
For example, an API method that has an "Unstructured Object" parameter named "urlparams" that is used to generate a tracking link that the user can attach arbitrary additional parameters to could be called like this, using any
combination of keys/values that the caller desires to pass:
&urlparams[foo]=bar&urlparams[biz]=baz
Data Object
A Data Object parameter type is used to provide a set of values for a model. This parameter is typically used in methods that create a new instance of a model or update the values for multiple fields of an existing model. The format is an object whose keys are the field names for the model with values for each being the value to set for that field on the model.
For example, an API method that has a "Data Object" parameter named "data" that is used to create Offer models could be called in the following way to create an Offer with values set for the "name", "status", and "description" fields:
&data[name]=TestOffer&data[status]=active&data[description]=TestDescription
Fields
Parameters that accept a Writable Model Field parameter are passed the same way as a primitive string parameter. This data type accepts the name of any writable field from a specific model.
For example, an API method used to update a single field of an Offer, which has a "Model Field" parameter named "field" and a string field named "value", could be called in the following way to change the value of the Offer.status field to "active":
&field=status&value=active
Array of Fields
Parameters that accept an Array of Model Fields are passed the same way as an Array of string parameters, using the "[]" notation after each value provided, but the values that can be passed are restricted to the field names for a specific model. This data type is typically implemented for methods that return models so that the number of fields returned can be restricted only to those the caller is interested in. When this parameter is optional it typically indicates that if no fields are passed it will return all the fields for the model, but if any fields are passed it will return only those which are enumerated.
For example, an API method that has an "Array of Model Fields" parameter named "fields" and scoped to the Offer model could be called in the following way if the "status", "id", and "name" fields are desired:
&fields[]=status&fields[]=id&fields[]=name