The CiviCRM API

CiviCRM has a stable, comprehensive API (Application Programming Interface) for accessing and managing data. The API is the recommended way for any extension or external program to interact with CiviCRM. CiviCRM also uses its own API to power all new UIs and bundled extensions.

Extensions can provide additional API entities or functionality. For help creating your own additions to the API, see API Architecture.

Why Use the API

The API is superior to executing raw SQL or calling internal CiviCRM functions, because it offers consistency and stability. It is designed to function predictably with every new release so as to preserve backwards compatibility when changes to the schema and BAO functions inevitably occur. Using the API also ensures all hooks and events are dispatched, allowing CiviCRM business logic and 3rd party integrations to function properly.

The best place to begin working with the API is your own test install of CiviCRM, using the API Explorer.

API Explorer

This is the go-to tool for both new and experienced developers. It gives detailed, interactive documentation on each entity, including the available actions and their parameters, and will write API code for you. To access it:

1. Log in to a CiviCRM site as an administrator.
   • This can even be the demo site.
2. Within the CivCRM menu, go to Support > Developer and either API Explorer v4 (URL /civicrm/api4) or the legacy API Explorer v3 (URL /civicrm/api3).

Warning

The API Explorer executes real API calls. It can modify data! So if you execute a Contact delete call, it will really delete the contact. As such, any experimenting is best done within a test site.

To get started, select an entity, for example Contact and an action to perform, for example Get. Use the GUI to select additional parameters to configure your API call; as you do, the API Explorer will generate code which you can copy & paste into your PHP, Javascript, REST or CLI application.

API Versions

CiviCRM's API has major versions which are independent of the CiviCRM version. The API version increments more slowly in order to maintain stability within the extension ecosystem. Typically, two versions of the API are maintained concurrently to allow gradual transitions. New releases of CiviCRM may add features to the API but will not break backward-compatibility within an API version.

• APIv4 is the current stable version, with new features being actively developed.
• APIv3 is minimally maintained with no new features and regression bug-fixes only.

Your code can use a combination of v3 and v4 API calls, but v4 is recommended for all new projects. Although there are no plans at the time of this writing to remove APIv3, upgrading existing code to use APIv4 is a good way to future-proof extensions.

Changelog

All important changes made to the API are recorded in APIv3 changes and APIv4 changes.

Entity Relationship Diagrams

To make better use of the API, it can be helpful to have a visual understanding of the relationship between entities available in the API. Entity Relationship Diagrams illustrating many of these are available as supplementary documentation to the API Explorer.