Before you start

Intended Audience 

Use of the API is aimed at developers with good coding knowledge and experience.

You should have a good knowledge of the concept of REST web services and JSON / JSON Serialization and how to implement this in your language of choice. This article does not intend to try and teach you that, and nor do our support or development team. Some sample PHP code is provided. If you do not use PHP, you will need to take the principles of the code below and apply to the language you are using.

Data Security 

You are exposing YOUR data (which could in turn mean data on YOUR customers) to another application to either pull or change information in OpenCRM and you need to plan and consider this carefully, as well as fully understand the code and methods you are working with.

Have you considered any security implications? Accessing data via the API is secured by SSL encryption, but we have no control over what or how you control access/encryption of the data once it lands on your side. Make sure you have sufficient security and access protection in place to your data once it is taken from OpenCRM.

Consider the security of the storage of the API keys or OpenCRM username and password that your application or code is using to connect to your OpenCRM system.

Data Validity / Integrity

The same level of data validation is not supported by the API at this time. Mandatory field checks are not in place and data validation (e.g. checking a number is entered into a number field, checking validity of email addresses etc is not supported). Duplication checks will not take place. You should make sure the data you are posting to the API is valid and sensible. 

Enable API

The API is disabled on OpenCRM systems by default. In order to start using the API, please contact support@opencrm.co.uk in order to request this to be enabled.

IP Restriction

It is possible to restrict access to the API to only certain IP addresses. Contact support@opencrm.co.uk if you wish to apply this restriction.

Please note that API restrictions setup in the web application settings do NOT apply to API access, API access needs to be restricted separately. 

TLS

For security reasons the API will only accept connections from clients using TLS version 1.2 or higher. Please check the version of the client/programming language you intend to use can connect using TLS protocol 1.2 or above. 

Request Recording/Logging/API Limits

For your info, security and peace of mind, all incoming REST API calls are recorded in your OpenCRM database. OpenCRM support has access to this. Your API requests are limited dependent on your subscription.

It is possible to restrict access to the API to only certain IP addresses. Contact support@opencrm.co.uk if you wish to apply this restriction.

Records modified or added by the API will show the following in their audit log:

Support

You may need further information to achieve your goals with the API. Simple questions can be directed to support@opencrm.co.uk, but if you have a more in depth API project, or your request is for something the API does not cover, this will be referred to your account manager to discuss with you further. Support requests on API functionality will be dealt with at a low priority and not within our usual contracted SLA times.

Accessing the API

Base URL and Methods

The API is a standard REST based API. It is possible to request the response to be sent in different formats based on your needs and preferences. The default and recommended response is JSON. 

Base URL

End Point / Method

end_point/method: this is the API function that you want to call e.g. "get_contact"

Authentication

API Keys

In order to use functions within the OpenCRM API, you will first need to authenticate your application with your OpenCRM system.

This is done using a pair of API Keys. Please contact Support to generate a pair of API keys that you can then use to connect to the OpenCRM API. 

Access via API keys gives full administrator access (full access to all data in the system and full access to edit and create records)

Authenticating API calls from your application

The API Key and Pass Key are sent as parameters in the API request (see Parameters section) 

Passing authentication details via HTTP header variables:

Some third party applications allow/require authentication details to be transmitted via HTTP header variabless. OpenCRM's api can support that. You need to set the following HTTP header variables:

Authentication using Login function and AccessKey

It is also possible to call the "Login" method of the API using the API keys which will generate and return an accesskey. The accesskey can then be provided as a parameter to the API calls instead of the API keys. 

Please note that similar to an OpenCRM web session,  the access key will time out if there is a period of no requests being received from that session.

Parameters

Parameters are passed to the API as GET or POST parameters. 

POST parameters can be provided as individual fields, a single string HTML payload or a single string JSON payload - see examples below. 

We recommend using POST especially when submitting record edits as otherwise the URLs can become quite long. 

We recommend using POST variables and as such most of the sample code is written using this.

Error Messages

If you send an invalid request you will receive an error message in return from the API. 

Each API method has specific error messages, which will outline the error. Below are some generic error messages caused by sending bad requests. 

Examples

Example GET request:

Sample PHP code using CURL:

Example POST request (raw payload):

Sample PHP Code using CURL: 

Example POST request (post fields):

Sample PHP Code using CURL: 

Example POST request (JSON):

Sample JSON:

Sample PHP Code using CURL: 

​$url='https://yoursystemname.opencrm.co.uk/api/rest/get_contact_list/';

$json = '{
"key": "rtyuiop45678fghjrt6g7hj89",
"passkey": "d4f5tgh7yu9ok6ftg78uyhj9i"
}';

$curl = curl_init($url);       
curl_setopt($curl, CURLOPT_POST, true); //we recommend using POST not GET
curl_setopt($curl, CURLOPT_POSTFIELDS, $json);
$curl_response = curl_exec($curl);
curl_close($curl); 

Field Names

For field names to use when making API calls including for use in the query string parameter (or reference for field names returned), please see this separate article:

Rest API Field Reference

End Point / Methods

Login Function

Overview

Performs a login to OpenCRM and returns a session ID that can then be used to authenticate with API methods instead of using API keys.

End point / method:

Parameters

Return Format (REST example):

The modified / created record ID is returned, or any validation errors.

Record Linking (BETA)

Overview

This function is in closed Beta but will be available to all customers in future updates. 

This function allows you to link records together.

Methods

Parameters

Return Format (REST example):

The ID of the parent record is returned if the link was made successfully

Campaigns (BETA)

Overview

This function is in closed Beta but will be available to all customers in future updates. 

This function allows you to link records to a campaign.

Methods

Parameters

Return Format (REST example):

String "Success" if a link was successfully made, or an error message string if not.

Optional parameters available to all functions