CareCloud 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 to manage vouchers, rewards, customer cards, segments, and other structures related to the customer account.
Learn about the CareCloud API, which Systems can use API to connect with CDP CareCloud. Like e-shops, POS, kiosks, booking, and other production systems. These systems usually process the customer data sets with their relationships or end-user applications like mobile Android and iOS APPs or web microsites that need unique customer data.
CareCloud API call structure
URI syntax
CareCloud API URI is assembled from multiple parts that are described in the example below:
{project_domain}
The domain of your CDP CareCloud installation. In the Reference guide, we use https://sandbox.crmcarecloud.com. You will get your project domain after confirming your CDP CareCloud plan.
{interface}
The interface describes what kind of data access your application will have. In CareCloud API we use two kinds of interface:
-
Enterprise interface (URL part:
enterprise-interface)
It is mainly created for e-shops, POS, kiosks, booking, and other similar production systems which need to get the data lists. -
Customer interface (URL part:
customer-interface)
It is created and used mainly for end-user applications like mobile Android and iOS APPs or web customer microsites needing unique customer data.
We have created and described two API interfaces, where the main difference is the purpose of the systems for which the API is created.
{version}
It represents the versioning of the CareCloud API. CareCloud API uses the following format:
vX.Y
Xrepresents a number of the major version. The major version number increases when significant changes or improvements are made. Usually, these changes are not backward-compatible with the previous version.Yrepresents a number of the minor version. The minor version number increases when minor features or bug fixes are applied. These changes should be backward-compatible with the previous version.
The current versions of CareCloud API are available in the Reference guide.
{resource_name}
This URL part represents the name of the resource you need to get data from. The API reference guide shows the complete list of resources and endpoints.
{resource_id}
A resource ID is used when you need to identify an accurate resource record. For example, while getting, updating, or deleting this record.
(query_parameters)
All query parameters are documented and described with every resource. CareCloud API use query parameters for pagination, filtration, or sorting of the API call results.
Request body
CareCloud API has request body in JSON format.
Request body is used in case of creating a new record, update an existing record or in action method call. In request body CareCloud API work with two kind of parameters describe below.
Read-only parameters
These parameters are used only in response to API calls and should not be set in the request body of the API call. Please avoid using them during the create, update or action method call.
Mandatory parameters
If a parameter is marked as required in the documentation, it is mandatory to use it in the CareCloud API call.
If a parent structure of the parameter 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 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.
HTTP headers
HTTP headers are an essential part of CareCloud API calls. They are used for language setup, authentication, or content identification.
Accept-Language
It is used when the integrator needs to set the language of the response (for example name, description, or note parameters). For more information, please check RFC 9110.
Accept-Language: cs, en-gb;q=0.8
Content-Type
It indicates the media type of the request body. In CareCloud API we required content type application/json. For more information about Content-Type please check RFC 9110.
Content-Type: application/json
Authorization
This header is used for the resources that requires authentication. Our authentication method is Bearer and you can find out more in the Authentication section.
Authorization: Bearer VDFBBAME577QVRSRTRLC93CNBGJYTRA4
HTTPS Verbs
CareCloud API is available only through the secure protocol HTTPS. CareCloud API supports the following selection of HTTP verbs:
GET verb
Make a GET request to retrieve data depending on URI and query string
Read more about GET here: RFC9110
POST verb
POST is used to create new resource/resources, and CareCloud API uses the POST verb for action methods calls.
Read more about POST here: RFC9110
PUT verb
PUT method updates an entire resource record specified by his unique ID.
Be Careful if you use the PUT method. You must update the entire resource record because you are updating the origin representation. Parameters that you skipped will be deleted in that record.
Read more about PUT here: RFC9110
DELETE verb
Use the DELETE verb to remove a resource specified by the unique ID. This verb is used only by some resources. Read more here: RFC9110
Status codes
Status codes represent the status of the API response.
| Success status code | Description |
|---|---|
| 200 OK | Successful |
| 201 Created | Resource was created |
| 204 No Content | In case of 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 |
Action methods
We use procedural calls in CareCloud API when resolving logic in CareCloud. For example, making product recommendations or recommending the best reward for customers depending on the purchase. We call them Action methods. The Action method can be called by existing resources, as in the example below:
Where {resource_name} represents a resource. The keyword actions identify the procedural call, and {action_method_name} is a unique name of the action. Action name is unique across the CareCloud API.
This is the example of the action “add customer” by resource segments:
POST https://{project_domain}/webservice/rest-api/enterprise-interface/v1.0/segments/{segment_id}/actions/add-customer