Getting started

CRM CareCloud REST API allows you to create and manage the customer accounts and related resources like countries, languages, currencies, sources or customer account statuses. You can use the API for management of vouchers, rewards, customer cards, segments and other structures related to customer account.

Domain structure

The domain structure is like <projectURL>/customer-interface/v1.0/customers where <projectURL> corresponds to the specific URL of your project. For example for project of company called Cortex, the <projectURL> could be https://cortex.crmcarecloud.com/webservice/rest-api/ or local URL https://project.carecloud.cz/webservice/rest-api/ or any other similar URL. REST API is available only through secure protocol HTTPS.

We have created and described two API types, where the main difference is the authentication method and the purpose of the systems for which the API is created.

Enterprise API

The Enterprise interface client authenticates with login and password. The Enterprise API is mainly created for e-shops, POS, kiosks, booking and other similar production systems which needs to get the data lists.
The domain structure for Enterprise interface API is like <projectURL>/enterprise-interface/v1.0/customers, where :

  • <projectURL> the specific URL of your project
  • enterprise-interface represents the type of API
  • v1.0 is the version of the API (this is only example, please the check actual version with your integration support)
  • customers is an example of the resource. List of resources is available in CRM CareCloud API Reference

Customer API

The Customer interface client authenticates with user name and token. The Customer API is created and used mainly for end user applications like mobile Android and iOS APPs or web customer microsites which needs to get the unique customer data.
The domain structure for the Customer interface API is like <projectURL>/customer-interface/v1.0/customers
Where :

  • <projectURL> the specific URL of your project
  • customer-interface represents the type of API
  • v1.0 is the version of the API (this is only example, please check the actual version with your integration support)
  • customers is an example of the resource. List of resources is available in CRM CareCloud API Reference

API call parameters

Every API call has the following parameters:

  • Path - contains domain, version, resource, identifier of resource, subresource and the subresource unique id: https://project.crmcarecloud.com/webservice/rest-api/customer-interface/v1.0/resource-name/resource_id/actions/action_id
  • Query string - uses as filter for results, pagination and limitation of results
  • Request body - contains structures for methods POST, PUT
  • Response body - contains all result data (resources or error information) in standard response structure

HTTPS Methods

REST API is available only through the secure protocol HTTPS. CRM CareCloud REST API uses selection of the basic HTTP methods:

[badge-blue GET]
Make a GET request to retrieve data depending on URI and query string

[badge-green POST]
POST is used to create new resources, we use it also for some action calls

[badge-grey PUT]
PUT method is used to update a resource specified by the unique id

[badge-red DELETE]
Method DELETE removes a resource specified by the unique id. This method is provided just by some specific resources.

API versioning

Versioning of the API has the following pattern:
<vX.Y>
where:

  • X represents the major version. The major version serial number increases when an incompatible API changes are made.
  • Y represents the minor version. The minor version serial number increases when we add a functionality in a backwards-compatible manner

If developers fix issues in the API a changelog report is published. Changelog contains a version of the API, date and description of the fix.

Actions

In special cases, if it is not possible to follow the RESTful way, we use the procedural call. We call it Action. It is possible the Action to be called by existing resources as in the example below.

[badge-green POST] <projectURL>/customer-interface/v1.0/resource-name/resource_id/actions/action_id

Where ‘resource-name’ represents a resource with its unique id - resource_id. Keyword actions identifies an action call and action_id is a unique id of the action that is represented by name of the action. Action name is unique across the API.

This is the example of the action “add customer” by resource segments:

[badge-green POST] <projectURL>/customer-interface/v1.0/segments/{segment_id}/actions/add-customer

Status codes

Status codes represent a status of the API response.

Success status code Description
200 OK Successful
201 Created Resource was created
204 No Content In case of the success without any response data


Error status code Description
400 Bad Request Bad input parameter. Error message specifies the detail
401 Unauthorized The client has invalid credentials or auth token
403 Forbidden The client does not exist or the client tried to access non authorized property/resource
404 Not Found The resource was not found
405 Method Not Allowed The resource does not support the specified HTTP method
429 Too Many Requests Too many requests - more than the resource limit
500 Internal Server Error Server is not working as expected
503 Service Unavailable Temporary state when the service is temporarily unavailable, overloaded or there is a maintenance window

Language version

It is used, when the integrator needs to get the right language version of the requested information (like name, description or note). To be able to identify the language version it is necessary to set HTTP header field accept-language.

GET / HTTP/1.1
Host: project.crmcarecloud.com
Accept-Language: cs

Read-only parameters

These kinds of parameters are used only in response to API calls, and they should not be set in the request body of the API call. Please avoid using them during use POST or PUT HTTP method. Every data structure parameter is marked in documentation, so you can see if parameter is read only or not.

Mandatory parameters

If a parameter is marked as mandatory in the documentation, it has to be used in API calls. If a parent structure is not mandatory and you won't use it, child parameters of that structure won't be required. If you use the parent structure in the API call, all child parameters that are marked as mandatory will be required. Every data structure parameter is marked in the documentation, so you can see if the parameter is mandatory or not.