1. Introduction
This document provides guidance for third-party developers on how to securely access and interact with a CiviPlus instance provided by Compuco. It outlines the setup steps completed by the CiviPlus team to enable API access, and provides instructions on how to connect to the API using the credentials provided.
It is intended for technical users who need to programmatically access CiviPlus data—typically for integration, automation, or custom development purposes.
As CiviPlus is built upon the Open Source CRM “CiviCRM” the document also includes links to official CiviCRM API documentation, guidance on using the API explorer, and notes on best practices and risks associated with direct API access.
2. Initial API setup tasks taken by Compuco
Prior to this process, the following steps will have been taken by the our team to setup the API and your API user:
Our team have enabled the API endpoint for the site. By default this is disabled for security reasons.
Our team has created a new “API User” and generated a strong CiviPlus API key for the user. When creating a new “User” CiviPlus has automatically created a linked CRM contact.
We have created a new role “API User”. It has been granted appropriate permissions based in the information we have about your API’s access requirements. The role has been assigned to the API user above.
We have also configured the API authentication settings according to the required defaults.
We have also enabled the API Key Management module and assigned permissions to the CiviCRM Admin role to create and update API keys for contact records.
As such you should have received the following from our team:
1. Username and password for your API user
These can be used to login to the system as the API user to access the API explorer, but are not needed for actual API calls. To learn more about the API explorer please see the section below.
Your API user is linked to a CRM contact. You can see this by logging in as the API user and navigating to the respective contact record:
Login and navigate to https://yoursitehere.com/user
Click the link “View contact record”.
2. CiviPlus API Key
This API key is your token for connecting to the API. This is data that is stored against the linked CRM contact record to your API user. Users with the “CiviCRM admin” role can update this by navigating to the API Key tab on the contact record:
3. Authentication settings
The sites authentication settings have been configured to support using the appropriate credentials:
As such there is no further configuration needed for your API user to connect.
3. To use the API explorer
To start with you may want to login to the site and access the “API explorer”. This can help with identifying the correct entity nomenclature and available actions.
In the API explorer you can view all the available entities that the API supports, and formulate your calls.
🚨Important🚨:
The menu links to the API explorer screens are not always shown in the main menu, but you will still be able access them directly using the URL’s below:
(There is also APIv3: <yoursitehere.com>/civicrm/api3 should you wish to use this) |
Once you’ve navigated to the API explorer you can see the following screen. Here you can explore Entities and Actions and formulate API calls.
4. Making your first API call
Let’s take an example of attempting to get a list of contacts from the API via a CURL call.
URL:
In order to make an API call you simply need to make a request to the following URL:
https://{yoursitehere.com}/civicrm/ajax/api4/{entity}/{action}
The available entities and actions can be obtained by viewing the API explorer. For our example the {entity} would be “Contact” and our {action} would be “get”.
As such the URL to use would be:
https://{yoursitehere.com}/civicrm/ajax/api4/contact/get
Authentication token:
You will also need to add your appropriate token. This is done by adding a suitable header:
Where the API key is the API we have provided you.
X-Requested-With
It is also recommended to add the following for compatibility (see CiviCRM documentation):
Query parameters:
As we are making an API call to get data it would be prudent to ensure we don’t get all the contacts in the database. Lets limit the results to 25 results max. To do this we add the JSON and URL encoded parameters. This can be done simply by using the API explorer which will provide us with the correct encoded params to add:
Do not pass cookies:
Depending on your settings you may also wish to ensure that no cookie parameter is added. The precise approach to do this will be different depending on the client you are using.
Other headers to add:
If you are connecting to a Compuco staging site, you may need to add an HTTP Basic Authentication header as well. To do this the request must contains a header field in the form of
, where <credentials> is the Base64 encoding of ID and password joined by a single colon :
There are various tutorials on how to add basic authentication to your CURL call online so we have not added those here.
Bringing it together:
Your final call should look something like the below:
5. Further documentation on the API:
For more information on the API please refer to the CiviCRM documentation:
We recommend using APIv4 for most use cases.
(See here for APIv3 https://docs.civicrm.org/dev/en/latest/api/v3/interfaces/#rest)
6. Please keep in mind that:
Direct API requests have the ability to alter large amounts of site data, which could affect the functioning of the site or your data. Please use carefully and at your own risk!