Contacts 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/contacts
Method: POST

Example of body request:

{
  "contacts": [
    {
      "customer_external_id": "12345", // External ID of the customer to which the contacts belong
      "contact_external_id": "C12345"
      "contact_name": "John Doe",      
      "attributes: {       
        "email": "example@example.com,
        "phone": "+420 7123 456 789",
        "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": "2025-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 "contacts" field is mandatory in the JSON body. Each contact object within the "contacts" array must include the following attributes:

• customer_external_id: Identifier for the customer to which the contacts belong, mandatory, max 255 characters.
• contact_external_id: Identifier for the contact, mandatory, max 255 characters.
• contact_name: Name of the contact, mandatory, max 255 characters.

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

Attributes field

The "attributes" field is an object that contains useful information about a given contact. In this field, you can add predefined contact attributes (system attributes), such as an email or phone. You can also add custom contact attributes, which you manage in the Customerscore.io application under the Attributes Management section.

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

{    
    "email": "example@example.com",
    "phone": "+420 7123 456 789",
    "city": "Brno",
    "age": 35,
    "is_admin": true,
    "last_contacted_at" "2025-04-25"
}

Each key in this object corresponds to the codename of contact 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 is required. It can hold up to 200 items, with the only mandatory field for each item being the date that represents when the data is valid or applicable.

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

{
  "date": "2024-04-29",
  "user_status": "active",
  "has_profile_picture": true,
  "resolved_tickets": 39,
  "last_purchase_date": "2024-04-25", 
}

Each key in this object corresponds to the codename of contact 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, the data will be assigned to each relevant customer and made visible in the contacts table on the customer detail page.

Responses

Code	Description
200	The contacts 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