Contact.php
This api exposes CiviCRM contacts.
Contacts are the main entity in CiviCRM and this api is more robust than most.
- Get action allows all params supported by advanced search.
- Create action allows creating several related entities at once (e.g. email).
- Create allows checking for duplicate contacts. Use getfields to list the full range of parameters and options supported by each action.
Table of Contents
Functions
- civicrm_api3_contact_create() : array<string|int, mixed>
- Create or update a Contact.
- _civicrm_api3_contact_create_spec() : mixed
- Adjust Metadata for Create action.
- civicrm_api3_contact_get() : array<string|int, mixed>
- Retrieve one or more contacts, given a set of search params.
- civicrm_api3_contact_getcount() : int
- Get number of contacts matching the supplied criteria.
- _civicrm_api3_contact_get_spec() : mixed
- Adjust Metadata for Get action.
- _civicrm_api3_contact_get_supportanomalies() : mixed
- Support for historical oddities.
- civicrm_api3_contact_delete() : array<string|int, mixed>
- Delete a Contact with given contact_id.
- _civicrm_api3_contact_check_params() : null
- Check parameters passed in.
- _civicrm_api3_contact_update() : CRM_Contact_BAO_Contact|CRM_Core_Error
- Helper function for Contact create.
- _civicrm_api3_greeting_format_params() : mixed
- Validate the addressee or email or postal greetings.
- _civicrm_api3_quicksearch_get_order_by() : string
- Get the order by string for the quicksearch query.
- civicrm_api3_contact_merge() : array<string|int, mixed>
- Merges given pair of duplicate contacts.
- _civicrm_api3_contact_merge_spec() : mixed
- Adjust metadata for contact_merge api function.
- civicrm_api3_contact_get_merge_conflicts() : array<string|int, mixed>
- Determines if given pair of contaacts have conflicts that would affect merging them.
- _civicrm_api3_contact_get_merge_conflicts_spec() : mixed
- Adjust metadata for contact_merge api function.
- civicrm_api3_contact_getmergedto() : array<string|int, mixed>
- Get the ultimate contact a contact was merged to.
- _civicrm_api3_contact_getmergedto() : int|false
- Get the contact our contact was finally merged to.
- _civicrm_api3_contact_getmergedto_spec() : mixed
- Adjust metadata for contact_merge api function.
- civicrm_api3_contact_getmergedfrom() : array<string|int, mixed>
- Get the ultimate contact a contact was merged to.
- _civicrm_api3_contact_getmergedfrom() : array<string|int, mixed>
- Get all the contacts merged into our contact.
- _civicrm_api3_contact_getmergedfrom_spec() : mixed
- Adjust metadata for contact_merge api function.
- _civicrm_api3_contact_proximity_spec() : mixed
- Adjust metadata for contact_proximity api function.
- civicrm_api3_contact_proximity() : array<string|int, mixed>
- Get contacts by proximity.
- _civicrm_api3_contact_getlist_params() : mixed
- Get parameters for getlist function.
- _civicrm_api3_contact_getlist_output() : array<string|int, mixed>
- Get output for getlist function.
- civicrm_api3_contact_duplicatecheck() : array<string|int, mixed>
- Check for duplicate contacts.
- _civicrm_api3_contact_duplicatecheck_spec() : mixed
- Declare metadata for contact dedupe function.
Functions
civicrm_api3_contact_create()
Create or update a Contact.
civicrm_api3_contact_create(array<string|int, mixed> $params) : array<string|int, mixed>
Parameters
- $params : array<string|int, mixed>
-
Input parameters.
Tags
Return values
array<string|int, mixed> —API Result Array
_civicrm_api3_contact_create_spec()
Adjust Metadata for Create action.
_civicrm_api3_contact_create_spec(array<string|int, mixed> &$params) : mixed
Parameters
- $params : array<string|int, mixed>
-
Array of parameters determined by getfields.
civicrm_api3_contact_get()
Retrieve one or more contacts, given a set of search params.
civicrm_api3_contact_get(array<string|int, mixed> $params) : array<string|int, mixed>
Parameters
- $params : array<string|int, mixed>
Tags
Return values
array<string|int, mixed> —API Result Array
civicrm_api3_contact_getcount()
Get number of contacts matching the supplied criteria.
civicrm_api3_contact_getcount(array<string|int, mixed> $params) : int
Parameters
- $params : array<string|int, mixed>
Tags
Return values
int_civicrm_api3_contact_get_spec()
Adjust Metadata for Get action.
_civicrm_api3_contact_get_spec(array<string|int, mixed> &$params) : mixed
Parameters
- $params : array<string|int, mixed>
-
Array of parameters determined by getfields.
_civicrm_api3_contact_get_supportanomalies()
Support for historical oddities.
_civicrm_api3_contact_get_supportanomalies(array<string|int, mixed> &$params, array<string|int, mixed> &$options) : mixed
We are supporting 'showAll' = 'all', 'trash' or 'active' for Contact get and for getcount
- hopefully some day we'll come up with a std syntax for the 3-way-boolean of 0, 1 or not set
We also support 'filter_group_id' & 'filter.group_id'
Parameters
- $params : array<string|int, mixed>
-
As passed into api get or getcount function.
- $options : array<string|int, mixed>
-
Array of options (so we can modify the filter).
civicrm_api3_contact_delete()
Delete a Contact with given contact_id.
civicrm_api3_contact_delete(array<string|int, mixed> $params) : array<string|int, mixed>
Parameters
- $params : array<string|int, mixed>
-
input parameters per getfields
Tags
Return values
array<string|int, mixed> —API Result Array
_civicrm_api3_contact_check_params()
Check parameters passed in.
_civicrm_api3_contact_check_params(array<string|int, mixed> &$params) : null
This function is on it's way out.
Parameters
- $params : array<string|int, mixed>
Tags
Return values
null_civicrm_api3_contact_update()
Helper function for Contact create.
_civicrm_api3_contact_update(array<string|int, mixed> $params[, int $contactID = NULL ]) : CRM_Contact_BAO_Contact|CRM_Core_Error
Parameters
- $params : array<string|int, mixed>
-
(reference ) an assoc array of name/value pairs.
- $contactID : int = NULL
-
If present the contact with that ID is updated.
Tags
Return values
CRM_Contact_BAO_Contact|CRM_Core_Error_civicrm_api3_greeting_format_params()
Validate the addressee or email or postal greetings.
_civicrm_api3_greeting_format_params(array<string|int, mixed> $params) : mixed
Parameters
- $params : array<string|int, mixed>
-
Array per getfields metadata.
Tags
_civicrm_api3_quicksearch_get_order_by()
Get the order by string for the quicksearch query.
_civicrm_api3_quicksearch_get_order_by(string $name, bool $isPrependWildcard, string $field_name) : string
Get the order by string. The string might be
- sort name if there is no search value provided and the site is configured to search by sort name
- empty if there is no search value provided and the site is not configured to search by sort name
- exactFirst and then sort name if a search value is provided and the site is configured to search by sort name
- exactFirst if a search value is provided and the site is not configured to search by sort name
exactFirst means 'yes if the search value exactly matches the searched field. else no'. It is intended to prioritise exact matches for the entered string so on a first name search for 'kath' contacts with a first name of exactly Kath rise to the top.
On short strings it is expensive. Per CRM-19547 there is still an open question as to whether we should only do exactMatch on a minimum length or on certain fields.
However, we have mitigated this somewhat by not doing an exact match search on empty strings, non-wildcard sort-name searches and email searches where there is no @ after the first character.
For the user it is further mitigated by the fact they just don't know the slower queries are firing. If they type 'smit' slowly enough 4 queries will trigger but if the first 3 are slow the first result they see may be off the 4th query.
Parameters
- $name : string
- $isPrependWildcard : bool
- $field_name : string
Return values
stringcivicrm_api3_contact_merge()
Merges given pair of duplicate contacts.
civicrm_api3_contact_merge(array<string|int, mixed> $params) : array<string|int, mixed>
Parameters
- $params : array<string|int, mixed>
-
Allowed array keys are: -int to_keep_id: main contact id with whom merge has to happen -int to_remove_id: duplicate contact which would be deleted after merge operation -string mode: "safe" skips the merge if there are no conflicts. Does a force merge otherwise.
Tags
Return values
array<string|int, mixed> —API Result Array
_civicrm_api3_contact_merge_spec()
Adjust metadata for contact_merge api function.
_civicrm_api3_contact_merge_spec(array<string|int, mixed> &$params) : mixed
Parameters
- $params : array<string|int, mixed>
civicrm_api3_contact_get_merge_conflicts()
Determines if given pair of contaacts have conflicts that would affect merging them.
civicrm_api3_contact_get_merge_conflicts(array<string|int, mixed> $params) : array<string|int, mixed>
Parameters
- $params : array<string|int, mixed>
-
Allowed array keys are: -int main_id: main contact id with whom merge has to happen -int other_id: duplicate contact which would be deleted after merge operation -string mode: "safe" skips the merge if there are no conflicts. Does a force merge otherwise.
Tags
Return values
array<string|int, mixed> —API Result Array
_civicrm_api3_contact_get_merge_conflicts_spec()
Adjust metadata for contact_merge api function.
_civicrm_api3_contact_get_merge_conflicts_spec(array<string|int, mixed> &$params) : mixed
Parameters
- $params : array<string|int, mixed>
civicrm_api3_contact_getmergedto()
Get the ultimate contact a contact was merged to.
civicrm_api3_contact_getmergedto(array<string|int, mixed> $params) : array<string|int, mixed>
Parameters
- $params : array<string|int, mixed>
Tags
Return values
array<string|int, mixed> —API Result Array
_civicrm_api3_contact_getmergedto()
Get the contact our contact was finally merged to.
_civicrm_api3_contact_getmergedto(array<string|int, mixed> $params) : int|false
If the contact has been merged multiple times the crucial parent activity will have wound up on the ultimate contact so we can figure out the final resting place of the contact with only 2 activities even if 50 merges took place.
Parameters
- $params : array<string|int, mixed>
Tags
Return values
int|false_civicrm_api3_contact_getmergedto_spec()
Adjust metadata for contact_merge api function.
_civicrm_api3_contact_getmergedto_spec(array<string|int, mixed> &$params) : mixed
Parameters
- $params : array<string|int, mixed>
civicrm_api3_contact_getmergedfrom()
Get the ultimate contact a contact was merged to.
civicrm_api3_contact_getmergedfrom(array<string|int, mixed> $params) : array<string|int, mixed>
Parameters
- $params : array<string|int, mixed>
Tags
Return values
array<string|int, mixed> —API Result Array
_civicrm_api3_contact_getmergedfrom()
Get all the contacts merged into our contact.
_civicrm_api3_contact_getmergedfrom(array<string|int, mixed> $params) : array<string|int, mixed>
Parameters
- $params : array<string|int, mixed>
Tags
Return values
array<string|int, mixed>_civicrm_api3_contact_getmergedfrom_spec()
Adjust metadata for contact_merge api function.
_civicrm_api3_contact_getmergedfrom_spec(array<string|int, mixed> &$params) : mixed
Parameters
- $params : array<string|int, mixed>
_civicrm_api3_contact_proximity_spec()
Adjust metadata for contact_proximity api function.
_civicrm_api3_contact_proximity_spec(array<string|int, mixed> &$params) : mixed
Parameters
- $params : array<string|int, mixed>
civicrm_api3_contact_proximity()
Get contacts by proximity.
civicrm_api3_contact_proximity(array<string|int, mixed> $params) : array<string|int, mixed>
Parameters
- $params : array<string|int, mixed>
Tags
Return values
array<string|int, mixed>_civicrm_api3_contact_getlist_params()
Get parameters for getlist function.
_civicrm_api3_contact_getlist_params(array<string|int, mixed> &$request) : mixed
Parameters
- $request : array<string|int, mixed>
Tags
_civicrm_api3_contact_getlist_output()
Get output for getlist function.
_civicrm_api3_contact_getlist_output(array<string|int, mixed> $result, array<string|int, mixed> $request) : array<string|int, mixed>
Parameters
- $result : array<string|int, mixed>
- $request : array<string|int, mixed>
Tags
Return values
array<string|int, mixed>civicrm_api3_contact_duplicatecheck()
Check for duplicate contacts.
civicrm_api3_contact_duplicatecheck(array<string|int, mixed> $params) : array<string|int, mixed>
Parameters
- $params : array<string|int, mixed>
-
Params per getfields metadata.
Tags
Return values
array<string|int, mixed> —API formatted array
_civicrm_api3_contact_duplicatecheck_spec()
Declare metadata for contact dedupe function.
_civicrm_api3_contact_duplicatecheck_spec(array<string|int, mixed> &$params) : mixed
Parameters
- $params : array<string|int, mixed>