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.
The best place to begin working with the API is your own test install of CiviCRM, using the 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:
- Log in to a CiviCRM site as an administrator.
- This can even be the demo site.
- Within the CivCRM menu, go to Support > Developer and either API Explorer v4 (URL
/civicrm/api4) or the legacy API Explorer v3 (URL
The API Explorer executes real API calls. It can modify data! So if you execute a
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
Use the GUI to select additional parameters to configure your API call; as you do, the API Explorer will generate code
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 now 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.
All important changes made to the API are recorded in APIv3 changes and APIv4 changes.