back to knowledgebase

OpenCRM API Developer and Reference Guide (Summary)

Rated 3.00 starRated 3.00 starRated 3.00 star Updated: 16 June 2022 10:16:55 OpenCRM::Add-in::SOAP

Please see our updated documentation here: OpenCRM API Developer Reference Guide

 

 

===========================

Before You Start
- Intended Audience
- Data Security
- Data Integrity
- Enable API
- IP Restriction
- TLS
- Logging/Limits
- Support

Calling the API
- Base URL
- Response Formats
- Authentication
- Parameters
- Examples Methods
- Login
- Field Names/Reference List

- List Functions - Count
 - get_activity_list_count
 - get_asset_list_count
 - get_company_list_count
 - get_contact_list_count
 - get_contract_list_count
 - get_lead_list_count
 - get_opportunity_list_count
 - get_product_list_count
 - get_project_list_count
 - get_quote_list_count
 - get_salesorder_list_count
 - get_invoice_list_count
 - get_purchaseorder_list_count
 - get_ticket_list_count

- List Functions - Basic
 - get_activity_list
 - get_asset_list
 - get_company_list
 - get_contact_list
 - get_contract_list
 - get_lead_list
 - get_opportunity_list
 - get_product_list
 - get_project_list
 - get_quote_list
 - get_salesorder_list
 - get_invoice_list
 - get_purchaseorder_list
 - get_ticket_list

- List Functions - Full
 - get_activity_list_full
 - get_asset_list_full
 - get_company_list_full
 - get_contact_list_full
 - get_contract_list_full
 - get_lead_list_full
 - get_opportunity_list_full
 - get_product_list_full
 - get_project_list_full
 - get_quote_list_full
 - get_salesorder_list_full
 - get_invoice_list_full
 - get_purchaseorder_list_full
 - get_ticket_list_full

- Retrieve Record
 - get_asset
 - get_activity  
 - get_company

 - get_contact
 - get_contract
 - get_lead
 - get_opportunity
 - get_product
 - get_project
 - get_ticket

- Retrieve Sales Record
 - get_quote
 - get_salesorder
 - get_invoice
 - get_purchaseorder

- Create/Edit Record
 - edit_asset
 - edit_activity
 - edit_company
 - edit_contact
 - edit_contact_custom1
 - edit_contact_custom2

 - edit_contract
 - edit_lead
 - edit_opportunity
 - edit_product
 - edit_project

- Create/Edit Sales Records
 - edit_quote
 - edit_salesorder
 - edit_invoice
 - edit_purchaseorder

- Reports
- Record Linking [BETA]
- Campaigns [BETA]
- Other Parameters

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:

Administrator (admin) 15-04-2016 15:54 Modified(API) Record modified by API call from IP: 12.34.45.56
 

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

https://yoursystemname.opencrm.co.uk/api/rest/{end_point}/

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) 

Name Description
key Your API Key
passkey Your API pass key

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:

Name Description
KEY1 Your API Key
KEY2 Your API pass key

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. 

Message Description
Invalid User Details - AUTHENTICATION FAILED Invalid API keys were provided
Unauthorized You either did not send full authentication details (missing one or both of key, passkey, accesscode) OR you sent a badly formatted request (e.g. invalid JSON). 

Examples

Example GET request:

https://yoursystemname.opencrm.co.uk/api/rest/get_contact_list/key/45ft6gh8uyj9i87hju9/passkey/5f76g9ij5fg67u89jh/keywords/bob one two

Sample PHP code using CURL:

$url='https://yoursystemname.opencrm.co.uk/api/rest/get_contact_list/key/rtyuiop45678fghjrt6g7hj89/passkey/d4f5tgh7yu9ok6ftg78uyhj9i';

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

Example POST request (raw payload):

https://yoursystemname.opencrm.co.uk/api/rest/get_contact_list

Sample PHP Code using CURL: 

$url='https://yoursystemname.opencrm.co.uk/api/rest/get_contact_list/';
$curl_post_data = "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, $curl_post_data);
$curl_response = curl_exec($curl);
curl_close($curl);

Example POST request (post fields):

https://yoursystemname.opencrm.co.uk/api/rest/get_contact_list

Sample PHP Code using CURL: 

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

$curl_post_data = array(
     "keywords" => "bob one two", //this will need to match the format of the phone number in the system - e.g. spaces, brackets etc could all cause problems in searching / finding results
     "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, $curl_post_data);
$curl_response = curl_exec($curl);
curl_close($curl);

Example POST request (JSON):

https://yoursystemname.opencrm.co.uk/api/rest/get_contact_list

Sample JSON:

{
"key": "rtyuiop45678fghjrt6g7hj89",
"passkey": "d4f5tgh7yu9ok6ftg78uyhj9i"
}

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:

/login

Parameters

Name Description
key Your API Key
passkey Your API pass key

Sample Response

On success, the function responds with a single string which is the access key for the login session.

{"12345tfgyhujijjljoijlijlkng76t76"}

 

List Functions - Count

Overview

Returns a count of the number of records in a list

Methods

get_activity_list_count
get_asset_list_count
get_company_list_count
get_contact_list_count
get_contract_list_count
get_lead_list_count
get_opportunity_list_count
get_product_list_count
get_project_list_count
get_ticket_list_count
get_quote_list_count
get_salesorder_list_count
get_invoice_list_count
get_purchaseorder_list_count

Parameters

Name Description
query_string Apply filters/search criteria to the list results.
Format is FIELDNAME|OPERATOR|FIELDVALUE
Supported operators are currently : =,LIKE, BEGINS, ENDS, CONTAINS
Consult OpenCRM support to help build these query strings / ask what field names are needed/available
limit_start Start results returned after this number of records.
limit_end End results returned after this number of records
keywords Perform a keyword search - fields searched depends on module

Return Format (REST example):

123

 

List Functions - Basic

Retrieve a list of records (basic information only)

Methods

get_activity_list
get_asset_list
get_company_list
get_contact_list
get_contract_list
get_lead_list
get_opportunity_list
get_product_list
get_project_list
get_ticket_list
get_user_list
get_quote_list
get_salesorder_list
get_invoice_list
get_purchaseorder_list

Parameters

Name Description
query_string Apply filters/search criteria to the list results.
Format is FIELDNAME|OPERATOR|FIELDVALUE
Supported operators are currently : =,LIKE, BEGINS, ENDS, CONTAINS>
Consult OpenCRM support to help build these query strings / ask what field names are needed/available
limit_start Start results returned after this number of records.
limit_end End results returned after this number of records
keywords Perform a keyword search - fields searched depends on module

Return Format (REST example):

(fieldname:value pair repeated for each field included in the list result)

[
  {
    "id": 12345,
    "crmid": 12345,
    "fieldname": "Field Value"
  },
  {
    "id": 45678,
    "crmid": 45678,
    "fieldname": "Field Value"
  }
]

 

List Functions - Full

Overview

Returns a list of records with, for each record, every field available on that record.

Please note that these functions will return a large volume of data and may take a long time to do so. 

We recommend either using the limit_start and limit_end parameters to only retrieve a small number of records at a time (you could first use the get_module_list function to get a list of records to know how many records to retrieve in total)
OR using the query_string parameter to only retrieve relevant records. For example, you could use the following query string to only return records modified since the last time you retrieved a full list:

get_contact_list/query_string/crmentity.modifiedtime|>|2018-11-15 12:46:00

Methods

get_activity_list_full
get_asset_list_full
get_company_list_full
get_contact_list_full
get_contract_list_full
get_lead_list_full
get_opportunity_list_full
get_product_list_full
get_project_list_full
get_ticket_list_full
get_quote_list_full
get_salesorder_list_full
get_invoice_list_full
get_purchaseorder_list_full

Parameters

Name Description
query_string Apply filters/search criteria to the list results.
Format is FIELDNAME|OPERATOR|FIELDVALUE
Supported operators are currently : =,LIKE, BEGINS, ENDS, CONTAINS
Consult OpenCRM support to help build these query strings / ask what field names are needed/available
limit_start Start results returned after this number of records.
limit_end End results returned after this number of records
keywords Perform a keyword search - fields searched depends on module

Return Format (REST example):

(fieldname:value pair repeated for every field on the record)

[
  {
    "id": 12345,
    "crmid": 12345,
    "fieldname": "Field Value"
  },
  {
    "id": 45678,
    "crmid": 45678,
    "fieldname": "Field Value"
  }
]

 

Consult / Retrieve  Functions

Overview

This allows you to retrieve a single record from OpenCRM The following list functions are available:

Methods

get_activity
get_asset
get_company
get_contact
get_contract
get_lead
get_opportunity
get_product
get_project
get_ticket

Parameters

Name Description
crmid The ID of the record to retrieve

Return Format (REST example):

(fieldname:value pair repeated for every field on the record)

{
  "fieldname":"fieldvalue",
  "record_id": "21707",
  "record_module": "Quotes",
}

 

Consult / Retrieve Sales Records  Functions

Overview

This allows you to retrieve a single record from OpenCRM. The sales modules differ from the normal module as retrieval of a sales record also returns the details of the products listed in the product grid of that record. 

Methods

get_quote
get_salesorder
get_invoice
get_purchaseorder

Parameters

Name Description
crmid The ID of the record to retrieve

Return Format (REST example):

(fieldname:value pair repeated for every field on the record)

(product_fieldname:product_value pair repeated for every field on the product grid)

"products": [
    {
      "lineid": "381",
      "linenumber": "1",
      "productid": "9109",
      "productname": "Product name",
      "product_fieldname":"product_fieldvalue",
    }
  ],
{
  "fieldname":"fieldvalue",
  "record_id": "21707",
  "record_module": "Quotes",
}

 

Reporting Functions

Overview

List functions allow you to get lists of data from OpenCRM reports.  Returns the results of the specified report (including all fields on that report).  This can be a standard report or a custom sql report built for you by OpenCRM.

Methods

get_record_list_from_report

Optional parameters for report functions

Name Description
reportid  The report ID to run (required)
 
isCustomReport true/false - specify this if it is a custom report
 

Return Format (REST example):

("Module_fieldname": "Field Value" pair repeated for every field in the report)

[
  {
    "id": 12345,
    "crmid": 12345,
    "Module_fieldname": "Field Value"
  },
  {
    "id": 45678,
    "crmid": 45678,
    "Module_fieldname": "Field Value"
  }
]

 

Create/Edit Records

Overview

Allows creation of new records or modification of existing records in OpenCRM

Methods

edit_activity
edit_contact
edit_contact_custom1
edit_contact_custom2
edit_asset
edit_company
edit_lead
edit_opportunity
edit_project
edit_helpdesk
edit_contracts

Parameters

Name Description
crmid Specify the record to edit, Send "0" to create a new record
fieldname/s You can pass as many fieldname paramaters in as you like and OpenCRM will set/update all the fields you pass in.
On existing records, only the fields specified will be updated, the current values will be retained on any fields which are not specified.
This documentation does not currently include a full list of available fields, but you can get the names of fields to update from the OpenCRM interface by inspecting the input elements on the edit pages. the "name" value on the input element is what you should use as the parameter name for the API call.
* On new records, you should always set "assigned_user_id" so the record has an owner (the value for assigned user id is the numeric ID of the user which can be obtained from the URL when viewing a user record.
 
 

Return Format (REST example):

The ID of the record modified or created is returned:

123456

 

Create/Edit Sales Records

Overview

This allows you to create or modify a single record in OpenCRM. The sales modules differ from the normal modules as creation/modification of a sales record also allows the details of the products listed in the product grid of that record to be updated. 

Methods

edit_quote
edit_salesorder
edit_invoice
edit_purchaseorder

Fields

This documentation does not currently include a full list of available fields, but you can get the names of fields to update from the OpenCRM interface by inspecting the input elements on the edit pages. the "name" value on the input element is what you should use as the parameter name for the API call.

* On new records, it is recommended that you set "assigned_user_id" so the record has an owner (the value for assigned user id is the numeric ID of the user which can be obtained from the URL when viewing a user record.

Parameters

Name Description
crmid Specify the record to edit, Send "0" to create a new record
fieldname/s Each field value should be passed as a separate parameter
You only need to pass in the fields you wish to update / set. Existing field data not passed in will be retained. 
 
 

Product Lines

When editing sales records, you can optionally update the product lines on that sales record.

Product line data can be submitted by either adding a POST field "products" containing all product data to be updated in a JSON string, or alternatively posting the entire edit as a JSON string. Some examples are shown below.

Adding new product lines

New product lines can be added by setting "lineid" (see list of fields below) to 0. A productid MUST be provided. 

Amending existing product lines

Existing product lines can be amended by passing in the "lineid" field matching the lineid of the product line that you wish to update (you can get a list of the associated product lines and their ids by first calling the get_quote method to retrieve the quote and product line details). 

Removing product lines

Product lines are removed by  sending product data and not including lineids that are currently on the record. For example, if the record currently has 4 product rows, lineids = 123, 456, 789 and 910 and the API receives a call to the edit method with lines 123, 456, 789 and 0, line 910 would be removed from the product lines (and a new line would be added).

Please note that once a product line has been deleted, it is permanently deleted and it cannot be recovered

Products as JSON String:

$curl_post_data = array(
     "key"=> "$key",
     "passkey"=> "$passkey",
     "code"=> "$code",
     "crmid" => 8660,
     "module" => 'Quotes',
     "assigned_user_id" => "1",
     "products" => '[
     {"lineid":"255","productid":"6437", "description":"Updated from API"},
     {"lineid":"256","productid":"6435", "description":"Updated from API"}
     ]'
     
     );

Entire post as JSON string (see also Examples section):

$curl_post_data = {
"key": "nosales",
"passkey": "nosales",
"code": "111111",
"crmid":"10172",
"module":"Quotes",
"subject":"A new one",
"products":[
     {"lineid":"268", 
     "linenumber": "1",
     "productid": "9109",
     "listprice1": "200000"
}]
}

Product line fields

The following product line fields can be set:

Please note that unlike in the web app, field mappings from product to sales records do not apply. All fields need to be set manually.

You only need to pass in the fields that you want to update and any mandatory fields. All other fields will retain their current values

Name Description
lineid REQUIRED. Set to 0 to add a new product line, otherwise set to the lineid to amend (as returned by the record retrieval method)
productid REQUIRED: Must be a valid, non-deleted OpenCRM product
linenumber Controls ordering of the product lines
description If not set, will default to that of the product
category The line category (for sub-totalling). Must be a valid category as available in the web application
quantity If not set, will default to 1. Must be a numeric value - up to 1 decimal place is supported. 
listprice1 Sell price in the default currency
listprice2 Sell price in secondary currency. If supplementary currency values are not passed in, they will be set to 0 - They will not calculate based on the base currency. 
listprice3 Sell price in third currency. If supplementary currency values are not passed in, they will be set to 0 - They will not calculate based on the base currency. 
listprice4 Sell price in fourth currency. If supplementary currency values are not passed in, they will be set to 0 - They will not calculate based on the base currency. 
listprice5 Sell price in fifth currency. If supplementary currency values are not passed in, they will be set to 0 - They will not calculate based on the base currency. 
buyprice Buy price in default currency
buyprice2 Buy price in secondary currency. If supplementary currency values are not passed in, they will be set to 0 - They will not calculate based on the base currency. 
buyprice3 Buy price in third currency. If supplementary currency values are not passed in, they will be set to 0 - They will not calculate based on the base currency. 
buyprice4 Buy price in fourth currency. If supplementary currency values are not passed in, they will be set to 0 - They will not calculate based on the base currency. 
buyprice5 Buy price in fifth currency. If supplementary currency values are not passed in, they will be set to 0 - They will not calculate based on the base currency. 
taxclass Tax class to apply to the row. Must be a valid tax class available in the web app. This will determine the tax percentage to apply. If not passed in on new records, will default to product value
prd_cf_1(..10) Custom product grid columns 1..10. Note that multi-currency custom product grid fields are not currently supported. 
discount Must be numeric value or percentage e.g. "10" or "10%"
supplierid ID of supplier company,. Must be a valid , non-deleted OpenCRM Company record id.
supplytype Product supply type. Must match a valid product supply type. If not passed in on new row, will default to product value
contract_term Must be integer value
commission_band The commission band to apply. Will determine commission percentage. If not set on new rows, will default to product value. 
minimummargin, maximumdiscount,  Can't be set from API - They will default to the values held on the product record
taxpercent, taxvalue, margin_percent, markup, commission_percent, commmission_amount,  Can't be set from API - They will be set/calculated by the system based on the other values passed in
pricebookid, saved_pricing_used, saved_pricing_tier, despatched_quantity, remaining_quantity Can't be set from the API - They will retain their existing values when editing existing rows. 
   

Return Format (REST example):

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

123456

 

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

edit_record_link

Parameters

Name Description
parent_id REQUIRED The primary record crmid - if you were linking records in the web app, this would be the main record on screen
child_id REQUIRED The crmid of the record you are linking to the primary record. If you were linking records in the web app, this would be the record you select from the sub tab to link to the primary record
 
 

Return Format (REST example):

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

123456

 

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

add_to_campaign

Parameters

Name Description
campaignid REQUIRED The crmid of the campaign to link to
recordid REQUIRED The crmid of the record you wish to add to the campaign
relationship The relationship to set on the record to campaign link
status The status to set on the record to campaign link
probability The probability to set on the record to campaign link
 
 

Return Format (REST example):

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

"Success"

 

Optional parameters available to all functions

Name Description
dateTimeOverride Dates and Times in the format of 2015-08-04 15:04:01 can be converted to standard php date time formats by adding to the url dateTimeOverride/ followed by the format, replacing spaces with "_" underscores and forward slashed with "*" stars eg d_F_Y_H:i
dateOverride Dates without the time in the format of 04-08-2015 can be converted in a similar way using dateOverride/ followed by the format.
Both the above can be combined in the same endpoint url
api/rest/get_project_list/dateTimeOverride/d_F_Y_H:i/dateOverride/d_F_Y
For API requester's requiring ISO 8601 compliant dates and times (such as ClicData) we recommending using the following overrides, dates without the time will have 00:00:00 time appended
api/rest/get_project_list/dateTimeOverride/c/dateOverride/c
limit_start, limit_end the record limit is currently set at 50000 records. If you need more records the set the limit_start to 0 and limit_end value to a reasonable amount above the number of records
change_assignedidtouser Change an Assigned User ID to a Username
Insert a comma to affect multiple fields eg Project_Developer,Assigned_to

 

Rate This Article
  • 1 star
  • 2 star
  • 3 star
  • 4 star
  • 5 star
Feedback and Comments
captcha code  


You may also be interested in: