Customers Data Import API

Last updated on 

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.

Rate Limiting

  • Maximum of 500 requests per minute.
  • If the limit is exceeded, the response will be:
    • HTTP status code: 429 Too Many Requests
    • Header: Retry-After – number of seconds to wait before retrying.

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.",
      "owner_email": "example@example.com", // Optional 
      "attributes: {        
        "crm_link": "https://example.com", // Link to customer profile in CRM
        "contact_email": "example@example.com", // Customer contact email
        "renewal_date": "2024-05-25", // 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
        }
      ]
    },
    ..... // Another customer   (up to 100 customers in a single API request)
  ]
}

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.
  • We strongly recommend sending customers in batches rather than one by one.
  • Each request can include up to 100 customers.
  • For best performance and reliability, we recommend:
    • 50–100 customers per request
    • Request body size below 5 MB

This reduces network overhead and helps avoid rate-limit issues.

Owner email field

  • owner_email: The owner's email address, optional, type of email, maximum 255 characters.

If provided, the customer will be automatically linked to the user in your account, if such a user exists.

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 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 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 generally contains product-usage data that feeds into the health score calculation. It can hold up to 200 items, and the only required attribute for each record is 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 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, including a scoring process that may take up to 30 minutes. After processing is complete, all users in the account will receive a notification regarding the newly imported customer 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
429     Too Many Requests
490     Unconfigured scoring