CMDataManager API

Getting Started

The CMDataManager API (Application Programming Interface) is a RESTful API enabling the integration of CMDataManager with other applications and systems including accounting, email marketing, CMS, SMS, ERP and eCommerce. The REST API makes use of 4 HTTP methods: GET, POST, PUT and DELETE which allow API users to retrieve, create, update and delete records within default and custom entities of CMDataManager. The HTTPS protocol should be used for all requests made to the API. All requests and responses are passed or returned in JSON format. The flexibility of the CMDataManager API means that users can use it to develop brand new applications or integrate and establish data flows between CMDataManager and other existing applications. For any further information regarding the API, please contact CMDataManager Support on: support@campaignmaster.co.uk.

Authentication

This section describes the /authenticate endpoint, necessary to authorise the client with the CMDataManager platform and make requests to the other API endpoints:

Authenticate

Authenticate the client with CMDataManager platform by requesting a token used for all other requests to the API.

Details

Endpoint
POST {{api-url}}/api/{{api-version}}/authenticate
Headers
                                    
										client_id: {{client-id}}
										client_secret: {{client-secret}}
										username: {{username}}
										password: {{password}}
Response – 200 OK
                                    
										{
											"token": "{{token}}"
										}

Example Request

                                        
											var client = new RestClient("{{api-url}}/api/{{api-version}}/authenticate");

											var request = new RestRequest(Method.POST);

											request.AddHeader("cache-control", "no-cache");
											request.AddHeader("client_id", "client_id");
											request.AddHeader("client_secret", "client_secret");
											request.AddHeader("username", "username");
											request.AddHeader("password", "password");

											IRestResponse response = client.Execute(request);
										

                                        
											$request = new HttpRequest();

											$request->setUrl('{{api-url}}/api/{{api-version}}/authenticate');

											$request->setMethod(HTTP_METH_POST);

											$request->setHeaders(array(
											  'cache-control' => 'no-cache',
											  'client_id' => 'client_id',
											  'client_secret' => 'client_secret',
											  'username' => 'username',
											  'password' => 'password'
											));

											try {
											  $response = $request->send();

											  echo $response->getBody();
											} catch (HttpException $ex) {
											  echo $ex;
											}

Limits

Each API call except the authentication one returns a number of different headers which provide feedback on the API limits for the API user making the requests. These headers are explained in more detail below.
Header Details
x-rate-limit-limit Integer value indicating the maximum number of calls per hour for the API user
x-rate-limit-remaining Integer value indicating the number of remaining calls per hour for the API user
x-rate-limit-reset Unix time indicating when the calls per hour limit will be reset
x-token-reset Unix time indicating when the authentication token will be reset

Methods

The CMDataManager API accepts requests of 4 different types: GET, POST, UPDATE, DELETE. Each of the 4 types are described in further details below.
Method Details
GET Use to retrieve data from the server
POST Use to send new resources to the server
PUT Use to update existing resources
DELETE Use to delete resources

Status Codes

As a response to each call, the CMDataManager API returns a status code indicating the result of the request. The status codes returned are described in details below.
Status Code Details
200 OK Returned when the API request is successful
201 Created Returned when the resource creation is successful
400 Bad Request Returned when there is a client error in the request e.g. malformed request syntax
401 Unauthorized Returned when authentication failed e.g. token missing/invalid
404 Not Found Returned when the resource cannot be found
429 Too Many Requests Returned when the limit of API requests per hour/month is reached
500 Internal Server Error Returned when an unexpected server error has occured

Entities

This section outlines all API endpoints which allow you to manage the entities within your CMDataManager account:

Get single record

Retrieve a specific record for an entity. Supported entities: account , lead , contact , task , opportunity , custom entity

Details

Endpoint
GET/{{entity}}/{{entity-external-id}}
Headers
                                    
										// Authorization: Bearer {{token}}
										string token
Response – 200 OK
                                    
										{
											"ExternalID": "ABC1D2E3",
											"Properties": {
												"FieldName": "FieldValue",
												"FieldName": "FieldValue"
											}
										}

Example Request

                                        
											var client = new RestClient("{{api-url}}/api/{{api-version}}/{{entity}}/{{entity-external-id}}");

											var request = new RestRequest(Method.GET);

											request.AddHeader("cache-control", "no-cache");
											request.AddHeader("Authorization", "Bearer {{token}}");

											IRestResponse response = client.Execute(request);
										

                                        
											$request = new HttpRequest();

											$request->setUrl('{{api-url}}/api/{{api-version}}/{{entity}}/{{entity-external-id}}');

											$request->setMethod(HTTP_METH_GET);

											$request->setHeaders(array(
											  'cache-control' => 'no-cache',
											  'Authorization' => 'Bearer {{token}}'
											));

											try {
											  $response = $request->send();

											  echo $response->getBody();
											} catch (HttpException $ex) {
											  echo $ex;
											}

Get multiple records

Retrieve multiple records for an entity. Supported entities: account , lead , contact , task , opportunity , custom entity

Details

Endpoint
GET/{{entity}}?fields={{fields}}&per_page={{per_page}}&page={{page}}&sort_by={{field}}&sort_order={{order}}
Headers
                                    
										// Authorization: Bearer {{token}}
										string token
Parameters
                                    
										// optional, comma-separated, example: e.g. fields=FirstName,LastName
										string fields

										// optional (required if page is used), example: e.g. per_page=10
										string per_page

										// optional (required if per_page is used), example: e.g. page=2
										string page
										
										// optional, example: e.g. sort_by=FirstName
										string sort_by
										
										// optional, example: e.g. sort_order=asc or sort_order=desc
										string sort_order
Response – 200 OK
                                    
										{
											"Total Records": "30",
											"Total Pages": "3",
											"Entity": [
												{
													"ExternalID": "ABC1D2E3",
													"Properties": {
														"FieldName": "FieldValue",
														"FieldName": "FieldValue"
													}
												},
												{
													"ExternalID": "FGH4I5J6",
													"Properties": {
														"FieldName": "FieldValue",
														"FieldName": "FieldValue"
													}
												}
											]
										}

Example Request

                                        
											var client = new RestClient("{{api-url}}/api/{{api-version}}/{{entity}}?fields={{fields}}&per_page={{per_page}}&page={{page}}");

											var request = new RestRequest(Method.GET);

											request.AddHeader("cache-control", "no-cache");
											request.AddHeader("Authorization", "Bearer {{token}}");

											IRestResponse response = client.Execute(request);
										

                                        
											$request = new HttpRequest();

											$request->setUrl('{{api-url}}/api/{{api-version}}/{{entity}}?fields={{fields}}&per_page={{per_page}}&page={{page}}');

											$request->setMethod(HTTP_METH_GET);

											$request->setQueryData(array(
											  'fields' 	 => '{{fields}}',
											  'per_page' => '{{per_page}}',
											  'page' 	 => '{{page}}'
											));

											$request->setHeaders(array(
											  'cache-control' => 'no-cache',
											  'Authorization' => 'Bearer {{token}}'
											));

											try {
											  $response = $request->send();

											  echo $response->getBody();
											} catch (HttpException $ex) {
											  echo $ex;
											}

Create single record

Create a single record for an entity. Supported entities: account , lead , contact , task , opportunity , custom entity

Details

Endpoint
For account, lead and contact: POST /{{entity}}
For tasks: POST /{{entity}}/{{entity-external-id}}/task
For opportunities: POST /{{entity}}/{{entity-external-id}}/opportunity
Headers
                                    
										Authorization: Bearer {{token}}
Body
                                    
										{
											"FieldName": "FieldValue",
											"FieldName": "FieldValue"
										}
Response – 201 Created
                                    
										{
											"ExternalID": "ABC1D2E3"
										}

Example Request

                                        
											var client = new RestClient("{{api-url}}/api/{{api-version}}/{{entity}}");

											var request = new RestRequest(Method.POST);

											request.AddHeader("Authorization", "Bearer {{token}}");
											request.AddHeader("Content-Type", "application/json");

											request.AddParameter("data", "{\"FieldName\":\"FieldValue\",\"FieldName\":\"FieldValue\"}", ParameterType.RequestBody);

											IRestResponse response = client.Execute(request);
										

                                        
											$request = new HttpRequest();

											$request->setUrl('{{api-url}}/api/{{api-version}}/{{entity}}');

											$request->setMethod(HTTP_METH_POST);

											$request->setHeaders(array(
											  'Authorization' => 'Bearer {{token}}',
											  'Content-Type' => 'application/json'
											));

											$request->setBody('{"FieldName":"FieldValue","FieldName":"FieldValue"}');

											try {
											  $response = $request->send();
											  echo $response->getBody();
											} catch (HttpException $ex) {
											  echo $ex;
											}

Update single record

Update a single record for an entity. Supported entities: account , lead , contact , task , opportunity , custom entity

Details

Endpoint
PUT /{{entity}}/{{entity-external-id}}
Headers
                                    
										Authorization: Bearer {{token}}
Body
                                    
										{
											"FieldName": "FieldValue",
											"FieldName": "FieldValue"
										}
Response – 200 OK
                                    
										{
											"Message": "Record updated."
										}

Example Request

                                        
											var client = new RestClient("{{api-url}}/api/{{api-version}}/{{entity}}/{{entity-external-id}}");

											var request = new RestRequest(Method.PUT);

											request.AddHeader("Authorization", "Bearer {{token}}");
											request.AddHeader("Content-Type", "application/json");

											request.AddParameter("data", "{\"FieldName\":\"FieldValue\",\"FieldName\":\"FieldValue\"}", ParameterType.RequestBody);

											IRestResponse response = client.Execute(request);
										

                                        
											$request = new HttpRequest();

											$request->setUrl('{{api-url}}/api/{{api-version}}/{{entity}}/{{entity-external-id}}');

											$request->setMethod(HTTP_METH_PUT);

											$request->setHeaders(array(
											  'Authorization' => 'Bearer {{token}}',
											  'Content-Type' => 'application/json'
											));

											$request->setBody('{"FieldName":"FieldValue","FieldName":"FieldValue"}');

											try {
											  $response = $request->send();
											  echo $response->getBody();
											} catch (HttpException $ex) {
											  echo $ex;
											}

Convert single lead entity

Convert a single record for an lead into account. Supported entity: lead

Details

Endpoint
PUT /lead/convert/{{lead-external-id}}
Headers
                                    
										Authorization: Bearer {{token}}
Response – 201 Created
                                    
										{
											"Account ExternalID": "ABC1D2E3"
										}

Example Request

                                        
											var client = new RestClient("{{api-url}}/api/{{api-version}}/lead/convert/{{entity-external-id}}");

											var request = new RestRequest(Method.PUT);

											request.AddHeader("Authorization", "Bearer {{token}}");
											request.AddHeader("Content-Type", "application/json");

											request.AddParameter("data", "{\"FieldName\":\"FieldValue\",\"FieldName\":\"FieldValue\"}", ParameterType.RequestBody);

											IRestResponse response = client.Execute(request);
										

                                        
											$request = new HttpRequest();

											$request->setUrl('{{api-url}}/api/{{api-version}}/lead/convert/{{entity-external-id}}');

											$request->setMethod(HTTP_METH_PUT);

											$request->setHeaders(array(
											  'Authorization' => 'Bearer {{token}}',
											  'Content-Type' => 'application/json'
											));

											$request->setBody('{"FieldName":"FieldValue","FieldName":"FieldValue"}');

											try {
											  $response = $request->send();
											  echo $response->getBody();
											} catch (HttpException $ex) {
											  echo $ex;
											}

Close single task

Close a single task of any entity. Supported entity: task

Details

Endpoint
PUT /Task/Close/{{task-external-id}}
Headers
                                    
										Authorization: Bearer {{token}}
Response – 200 OK
                                    
										{
											"Message": "Record updated."
										}

Example Request

                                        
											var client = new RestClient("{{api-url}}/api/{{api-version}}/task/close/{{task-external-id}}");

											var request = new RestRequest(Method.PUT);

											request.AddHeader("Authorization", "Bearer {{token}}");
											request.AddHeader("Content-Type", "application/json");

											request.AddParameter("data", "{\"FieldName\":\"FieldValue\",\"FieldName\":\"FieldValue\"}", ParameterType.RequestBody);

											IRestResponse response = client.Execute(request);
										

                                        
											$request = new HttpRequest();

											$request->setUrl('{{api-url}}/api/{{api-version}}/task/close/{{task-external-id}}');

											$request->setMethod(HTTP_METH_PUT);

											$request->setHeaders(array(
											  'Authorization' => 'Bearer {{token}}',
											  'Content-Type' => 'application/json'
											));

											$request->setBody('{"FieldName":"FieldValue","FieldName":"FieldValue"}');

											try {
											  $response = $request->send();
											  echo $response->getBody();
											} catch (HttpException $ex) {
											  echo $ex;
											}

Delete single record

Delete a specific record for an entity. Supported entities: account , lead , contact , task , opportunity , custom entity

Details

Endpoint
DELETE/{{entity}}/{{entity-external-id}}
Headers
                                    
										// Authorization: Bearer {{token}}
										string token
Response – 200 OK
                                    
										{
											"Message": "Record deleted."
										}

Example Request

                                        
											var client = new RestClient("{{api-url}}/api/{{api-version}}/{{entity}}/{{entity-external-id}}");

											var request = new RestRequest(Method.DELETE);

											request.AddHeader("cache-control", "no-cache");
											request.AddHeader("Authorization", "Bearer {{token}}");

											IRestResponse response = client.Execute(request);
										

                                        
											$request = new HttpRequest();

											$request->setUrl('{{api-url}}/api/{{api-version}}/{{entity}}/{{entity-external-id}}');

											$request->setMethod(METHOD_DELETE);

											$request->setHeaders(array(
											  'cache-control' => 'no-cache',
											  'Authorization' => 'Bearer {{token}}'
											));

											try {
											  $response = $request->send();

											  echo $response->getBody();
											} catch (HttpException $ex) {
											  echo $ex;
											}

Fields

This section outlines all the API endpoints that can be used to manage fields in the CMDataManager platform:

Get entity fields

Retrieve all fields for an entity. Supported entities: account , lead , contact , opportunity , custom entity

Details

Endpoint
GET/{{entity}}/fields
Headers
                                    
										// Authorization: Bearer {{token}}
										string token
Parameters
                                    
										// optional (required if page is used), example: e.g. per_page=10
										string per_page

										// optional (required if per_page is used), example: e.g. page=2
										string page
Response – 200 OK
                                    
										{
											"Total Records": "30",
											"Total Page": "3",
											"Field": [
												{
													"ExternalID": "ABC1D2E3",
													"Properties": {
														"FieldName": "FieldValue",
														"FieldName": "FieldValue"
													}
												},
												{
													"ExternalID": "FGH4I5J6",
													"Properties": {
														"FieldName": "FieldValue",
														"FieldName": "FieldValue"
													}
												}
											]
										}

Example Request

                                        
											var client = new RestClient("{{api-url}}/api/{{api-version}}/{{entity}}/fields?per_page={{per_page}}&page={{page}}");

											var request = new RestRequest(Method.GET);

											request.AddHeader("cache-control", "no-cache");
											request.AddHeader("Authorization", "Bearer {{token}}");

											IRestResponse response = client.Execute(request);
										

                                        
											$request = new HttpRequest();
											$request->setUrl('{{api-url}}/api/{{api-version}}/{{entity}}/fields?per_page={{per_page}}&page={{page}}');
											$request->setMethod(HTTP_METH_GET);

											$request->setQueryData(array(
											  'per_page' => '10',
											  'page' => '1'
											));

											$request->setHeaders(array(
											  'cache-control' => 'no-cache',
											  'Authorization' => 'Bearer {{token}}'
											));

											try {
											  $response = $request->send();

											  echo $response->getBody();
											} catch (HttpException $ex) {
											  echo $ex;
											}

Contact

Hygeia Building
66-68 College Road
Harrow
Middlesex
HA1 1BE
United Kingdom

+44 (0) 20 8863 5334

Useful Links

Privacy Policy

Cookie Policy

Site Map

Request a Demo

Free Demo

Campaign Master (UK) Ltd. 2024