Customer Data Import API

API Reference:
link to reference

Authentication

You need an API token (customerscore-key) to connect to our REST API. You can generate your token in the Customerscore.io application under the API settings section. Keep this token secret and store it in a safe place!

Request header requirements

Content-Type: application/json
customerscore-key: "your-generated-key"

Please ensure to include the generated token in the request header as customerscore-key. Additionally, specify Content-Type: application/json in the header.

API Request Specifications

URL: https://api.customerscore.io/api/v1/customers
Method: POST

Example of body request:

{
  "customers": [
    {
      "external_id": "12345",
      "name": "Knapp-Cruz Inc.",      
      "attributes: {        
        "crm_link": "https://example.com", // Link to customer profile in CRM
        "contact_email": "example@example.com, // Customer contact email
        "renewal_date": "2024-0525", // Date of next renewal
        "attribute_codename_from_your_app": "abcd", // String value
        "attribute_codename_from_your_app": 1234, // Number value
        "attribute_codename_from_your_app": true // Boolean value
        "attribute_codename_from_your_app": "2024-08-14" // Date value
      },
      "metrics": [
        {
          "date": "2024-04-29", // Must be unique for each item in "metrics" array
          "metric_codename_from_your_app": "abcd", // String value
          "metric_codename_from_your_app": 1234, // Number value
          "metric_codename_from_your_app": true // Boolean value
          "metric_codename_from_your_app": "2024-08-14" // Date value
        }
      ]
    }
  ]
}

Maximum request body size is limited to 5 MB. The "customers" field is mandatory in the JSON body. Each customer object within the "customers" array must include the following attributes:

• external_id: Identifier for the customer, mandatory, max 255 characters.
• name: Name of the customer, mandatory, max 255 characters.

You can include up to 100 customers in a single API request.

Attributes field

The "attributes" field is an object that contains useful information about a given customer. In this field, you can add predefined attributes (system attributes), such as a link to CRM, customer contact email, or date of next renewal. Additionally, it can include attributes used for score calculation. You can also add custom attributes, which you manage in the Customerscore.io application under the Attributes Management section.

Here’s an example structure of  "attributes" object:

{    
    "crm_link": "https://your-crm-link.com/12345",
    "contact_email": "example@example.com",
    "renewal_date": "2025-05-25",
    "country_name": "Czech republic",
    "customers_count": 99,
    "has_avatar": true,
    "renewal_date" "2025-05-25"
}

Each key in this object corresponds to the codename of attribute configured in the Customerscore.io application under the Attributes Management section.

Please note that the key must precisely match the codename attribute, which is case-sensitive. Only keys that match will be stored in the application, and a score will be calculated from their values, or they will be utilized differently according to the settings in the application.

Metrics field

The "metrics" field, which typically contains data used for score calculation, is required. It can hold up to 200 items, with the only mandatory attribute for each item being the date on which the score will be calculated.

Here’s an example structure of one item in the "metrics" array:

{
	"date": "2024-04-29",
	"country": "Czechia",
        "has_picture": true,
	"resolved_tickets": 39,
        "created_at": "2024-08-15" 
}

Each key in this object corresponds to the codename of metric configured in the Customerscore.io application under the Metrics Management section.

Please note that the key must precisely match the codename metric, which is case-sensitive. Only keys that match will be stored in the application, and a score will be calculated from their values, or they will be utilized differently according to the settings in the application.

Upon successful data import, internal processing will occur, and all users in the account will receive a notification regarding the newly imported customers' data.

Responses

Code	Description
200	The customers data has been successfully received and forwarded for processing.
400	Bad request
401	Unauthorized. Missing parameter 'customerscore-key' in the header
403	Forbidden. Invalid key
405	Method Not Allowed, only POST method is allowed
406	Not Acceptable
490     Unconfigured scoring