API Reference

Quickstart CareCloud API

Detailed manual for the CareCloud API authentication.

Enterprise interface

👍

If you are building a mobile application, a customer portal, or a kiosk, see Customer interface instead.

Use this guide if you are building a POS system, an e-commerce backend, or a business intelligence integration.

Before you start

You need the following before making your first API call:

  • Project URL - the domain of your CareCloud installation (for example, sandbox.crmcarecloud.com)
  • External application ID - provided by your CareCloud administrator
  • API user credentials - a username and password for an API user with the webservice user group, provided by your CareCloud administrator

📘

If you do not have direct access to CareCloud, contact the responsible person in your organisation to provide these values.

Step 1: Get a Bearer token

Call POST /users/actions/login to authenticate and receive a Bearer token. No Authorization header is required for this request.

POST https://sandbox.crmcarecloud.com/webservice/rest-api/enterprise-interface/v1.0/users/actions/login
Content-Type: application/json
Accept-Language: cs, en-gb;q=0.8

{
  "user_external_application_id": "89d1a6111b3fb6e74665d948",
  "login": "fabulous_user",
  "password": "password_example"
}

The response includes a bearer_token value. Copy it - you will use it in every subsequent request.

{
  "data": {
    "bearer_token": "09359095c5da43c7ae11e710eabce49418715a6a",
    "valid_to": "2023-01-04 10:31:56",
    "user": {
      "user_id": "838b73aacb5ac326cec4030c80",
      "login": "fabulous_user",
      "first_name": "Fabulous",
      "last_name": "Legend",
      "email": "[email protected]",
      "phone": 420123828931,
      "user_role_id": "86e05affc7a7befcd513ab400",
      "store_id": "86e05affc7a7abecd513ab400"
    }
  }
}

Step 2: Make your first API call

Add the bearer_token value to the Authorization header and call GET /customers.

GET https://sandbox.crmcarecloud.com/webservice/rest-api/enterprise-interface/v1.0/customers
Content-Type: application/json
Accept-Language: cs, en-gb;q=0.8
Authorization: Bearer 09359095c5da43c7ae11e710eabce49418715a6a

A successful response returns a list of customers and the total number of matching records:

{
  "data": {
    "customers": [
      {
        "customer_id": "8ea6abece4cd0a4ded0a29f093",
        "personal_information": {
          "gender": 1,
          "first_name": "John",
          "last_name": "Smith",
          "birthdate": "985-02-12",
          "email": "[email protected]",
          "phone": "420523828931",
          "language_id": "en",
          "store_id": "8bed991c68a4",
          "address": {
            "address1": "Old Town Square",
            "address2": "34",
            "address3": "",
            "address4": "",
            "address5": "",
            "address6": "",
            "address7": "",
            "zip": "11000",
            "city": "Prague 1",
            "country_code": "cz"
          },
          "agreement": {
            "agreement_gtc": 1,
            "agreement_profiling": 1,
            "agreement_marketing_communication": 1,
            "custom_agreements": [
              {
                "agreement_id": "89ce2a1b9b01f5c939fb1e20cd",
                "agreement_value": 2
              }
            ]
          }
        },
        "last_change": "2019-06-23 11:47:22",
        "state": 1
      }
    ],
    "total_items": 1
  }
}

Step 3: What to do next

  • Token validity and re-authentication - tokens expire after 7 hours by default. For details on expiry handling and re-authentication, see Enterprise interface authentication.
  • Production integration guidance - before deploying, review the Integration best practices page.
  • Postman collection - to explore the API interactively before writing code, import the Postman collection. See Tools.

Customer interface

👍

If you are building a POS system, an e-commerce backend, or a business intelligence integration, see Enterprise interface instead.

Use this guide if you are building a mobile application, a web portal, a kiosk, or a smart device application.

Before you start

You need the following before making your first API call:

  • Project URL - the domain of your CareCloud installation (for example, sandbox.crmcarecloud.com)
  • External application ID - provided by your CareCloud administrator

📘

If you do not have direct access to CareCloud, contact the responsible person in your organisation to provide these values.

Step 1: Create a device token

Call POST /tokens to create an access token for your application installation. This request does not require an Authorization header.

POST https://sandbox.crmcarecloud.com/webservice/rest-api/customer-interface/v1.0/tokens
Content-Type: application/json
Accept-Language: cs, en-gb;q=0.8

{
  "device": {
    "device_id": "123456",
    "device_system": "OSX",
    "device_name": "Test device",
    "device_type": "iPhone"
  },
  "setup": {
    "language_id": "en",
    "allowed_gps": true,
    "allowed_notifications": false
  },
  "external_application_id": "81eaeea13b8984a169c490a325"
}

The response returns a token_id. This value is your Bearer token for all subsequent requests.

{
  "data": {
    "token_id": "4d8121dea8ae3c7b7fc66e6924ecc466dc7aa13e299ac757d87533ab2630f31bd906aadf"
  }
}

Step 2: Log in as a customer (optional)

📘

Skip this step if your application does not need customer-specific data. The device token alone is sufficient for endpoints that do not require a logged-in customer.

Call POST /tokens/{token_id}/actions/login to associate the token with a customer account. Use the token_id from step 1 in both the URL path and the Authorization header.

POST https://sandbox.crmcarecloud.com/webservice/rest-api/customer-interface/v1.0/tokens/4d8121dea8ae3c7b7fc66e6924ecc466dc7aa13e299ac757d87533ab2630f31bd906aadf/actions/login
Content-Type: application/json
Accept-Language: cs, en-gb;q=0.8
Authorization: Bearer 4d8121dea8ae3c7b7fc66e6924ecc466dc7aa13e299ac757d87533ab2630f31bd906aadf

{
  "login_type": "email",
  "login_value": "[email protected]",
  "password": "password_example"
}

The response returns the customer_id of the authenticated customer:

{
  "data": {
    "customer_id": "8ea6abece4cd0a4ded0a29f093"
  }
}

Step 3: Make your first API call

Add the token_id value to the Authorization header and call GET /customers.

GET https://sandbox.crmcarecloud.com/webservice/rest-api/customer-interface/v1.0/customers
Content-Type: application/json
Accept-Language: cs, en-gb;q=0.8
Authorization: Bearer 4d8121dea8ae3c7b7fc66e6924ecc466dc7aa13e299ac757d87533ab2630f31bd906aadf

A successful response returns the customer record for the logged-in customer:

{
  "data": {
    "customers": [
      {
        "customer_id": "8ea6abece4cd0a4ded0a29f093",
        "personal_information": {
          "gender": 1,
          "first_name": "John",
          "last_name": "Smith",
          "birthdate": "985-02-12",
          "email": "[email protected]",
          "phone": "420523828931",
          "language_id": "en",
          "store_id": "8bed991c68a4",
          "address": {
            "address1": "Old Town Square",
            "address2": "34",
            "address3": "",
            "address4": "",
            "address5": "",
            "address6": "",
            "address7": "",
            "zip": "11000",
            "city": "Prague 1",
            "country_code": "cz"
          },
          "agreement": {
            "agreement_gtc": 1,
            "agreement_profiling": 1,
            "agreement_marketing_communication": 1,
            "custom_agreements": [
              {
                "agreement_id": "89ce2a1b9b01f5c939fb1e20cd",
                "agreement_value": 2
              }
            ]
          }
        },
        "last_change": "2019-06-23 11:47:22",
        "state": 1
      }
    ],
    "total_items": 1
  }
}

Step 4: What to do next

  • Token behaviour and device identifier requirements - for details on token lifecycle and how device_id affects token validity, see Customer interface authentication.
  • Production integration guidance - before deploying, review the Integration best practices page.
  • Postman collection - to explore the API interactively before writing code, import the Postman collection. See Tools.