API Options¶

APIv3 Deprecation

API version 3 is now deprecated. Version 4 is recommended.

There are many API Options accepted by the CiviCRM API. These options allow the developer to add in more parameters to the resulting Query that is run against the database. E.g. Limit, Sort. You can explore these options using the the API Explorer and the APIv3 Examples However, some parameters are particularly dynamic or generic; these may not be explained well by the auto-generated documentation. The format for passing options as parameters using the REST interface is explained at REST interface.

sequential¶

Action: get
Type: bool
Default: FALSE
Compatibility: ??
Description:

Determine whether the returned records are indexed sequentially (0, 1, 2, ...) or by ID.

Example without sequential:

$result = civicrm_api('UFMatch', 'get', array(
  'version' => 3,
  'uf_id' => $user->uid,
));
$contactId = $result['values'][$result['id']]['contact_id'];

Example with sequential:

$result = civicrm_api('UFMatch', 'get', array(
  'version' => 3,
  'uf_id' => $user->uid,
  'sequential' => 1,
));
$contactId = $result['values'][0]['contact_id'];

Note that a single record is returned in this example - whenever a single record is returned the entity_id of that record should be in $result['id']

options.limit¶

Action: get
Type: int
Default: 25
Compatibility: ??
Description:

The maximum number of records to return

Example:

civicrm_api('UFMatch', 'get', array(
  'version' => 3,
  'uf_id' => $user->uid,
  'options' => array(
    'limit' => 25,
  ),
));

options.offset¶

Action: get
Type: int
Default: 0
Description:

The numerical offset of the first result record

Example:

civicrm_api('UFMatch', 'get', array(
  'version' => 3,
  'uf_id' => $user->uid,
  'options' => array(
    'limit' => 25,
    'offset' => 50,
  ),
));

options.sort¶

Action: get
Type: ??
Default: ??
Parameters: field name, order (ASC / DESC)
Description:

The criterion to sort on

Example

civicrm_api3('Contact', 'get', array(
  'sequential' => 1,
  'return' => "contact_type",
  'options' => array('sort' => "contact_type ASC"),
));

options.reload¶

Action: create
Type: bool
Default: FALSE
Compatibility: v4.4+
Description:

Whether to reload and return the final record after the saving process completes.

Example:

civicrm_api('Contact', 'create', array(
  'version' => 3,
  'contact_type' => 'Individual',
  'first_name' => 'First',
  'last_name' => 'Last',
  'nick_name' => 'Firstie',
  'options' => array(
    'reload' => 1,
  ),
));

options.match¶

Action: create | replace
Type: string | array
Default: NULL
Compatibility: v4.4+
Description:

Attempt to update an existing record by matching against the specified field.

If one matching record already exists, then the record will be updated.
If no matching record exists, then a new one will be inserted.
If multiple matching records exist, then return an error.

Example:

civicrm_api('Contact', 'create', array(
  'version' => 3,
  'contact_type' => 'Individual',
  'first_name' => 'Jeffrey',
  'last_name' => 'Lebowski',
  'nick_name' => 'The Dude',
  'external_identifier' => '1234',
  'options' => array(
    'match' => 'external_identifier',
  ),
));

options.match-mandatory¶

Action: create | replace
Type: string | array
Default: NULL
Compatibility: v4.4+
Description:

Attempt to update an existing record by matching against the specified field.

If one matching record already exists, then the record will be updated.
If no matching record exists, then return an error.
If multiple matching records exist, then return an error.

Example:

civicrm_api('Contact', 'create', array(
  'version' => 3,
  'contact_type' => 'Individual',
  'first_name' => 'Jeffrey',
  'last_name' => 'Lebowski',
  'nick_name' => 'The Dude',
  'external_identifier' => '1234',
  'options' => array(
    'match-mandatory' => 'external_identifier',
  ),
));