1. Introduction
This document provides guidance for third-party developers on how to securely access and interact with a CiviPlus instance. It outlines the setup steps required 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. Setting up an API "User"
The first step in connecting to the API is to setup an API "User". This is a user account (like any other user account that you have created to access your site) that has however been configured to allow secure, programmatic access to the platform. Creating a dedicated API user ensures that integration or automation scripts do not interfere with operational user accounts and that appropriate security controls are applied.
There are two possible scenarios for setting up your API user:
CiviPlus team provides your API user
In this case, the CiviPlus team will have handled the technical setup steps on your behalf, including enabling the API endpoint, creating a dedicated user account, assigning permissions, and generating your API key. You will receive a set of credentials and can proceed directly to using the API.You are setting up the API user yourself
This applies if you are managing your own environment or if delegated access has been granted. You will need to manually enable the API, configure the authentication settings, assign the appropriate permissions, and generate the API key.
In either case, the API user is essential for ensuring secure, permission-based access to the CiviPlus API and for maintaining an auditable access trail for API activity.
2.1 CiviPlus team provides your API user
If the CiviPlus team has set your API user up for you we will have performed the following tasks:
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.
2.2 You are setting up the API user yourself
If your API user has not been pre-configured by the CiviPlus team, you can create one yourself by following the steps below.
By default, access to the API Key Management extension for step 2 below may be disabled. Please contact you CiviPlus account manager who can enable this for you if needed.
These instructions assume you have administrative access to your CiviPlus instance and the necessary permissions to manage users and contacts.
Step 1: Create a New User Account
Go to People > Add User in your site administration menu.
Fill in the user details (username, email, etc.). This user will serve as your dedicated API account.
Set a strong password.
Set a suitable role for the API user
Note: Be cautious to only grant the minimum permissions required for the integration.
Save the new user.
Upon creation, the system will automatically create a linked CiviCRM contact record for this user.
Step 2: Generate and Assign an API Key
Navigate to the Contact Record of the API user created above.
Click the API Key tab:
Generate a new API key.
Copy and store this key securely—this will be used to authenticate API requests.
Once the above steps are complete, your API user will be ready to authenticate and make calls to the CiviPlus API. You can test this setup by logging in as the API user and accessing the API Explorer (see below).
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!