Contact upload

Import contact data into Customerscore via the Contacts API endpoint.

For interactive API documentation, see the Swagger reference (opens in a new tab).

Endpoint

Requirements

Contacts are directly linked to a specific customer existing in Customerscore. Before sending contacts, you must first have the customers stored in Customerscore.

Request Body

The contacts field is mandatory in the JSON body. Each contact object within the contacts array must include the following attributes:

Maximum request body size is limited to 5 MB. You can include up to 100 contacts in a single API request.

Example Request

curl -X POST "https://api.customerscore.io/api/v1/contacts" \
  -H "Content-Type: application/json" \
  -H "customerscore-key: your-generated-key" \
  -d '{
    "contacts": [
      {
        "customer_external_id": "12345",
        "contact_external_id": "C12345",
        "contact_name": "John Doe",
        "attributes": {
          "email": "john.doe@example.com",
          "phone": "+420 7123 456 789"
        },
        "metrics": [
          {
            "date": "2025-04-29",
            "resolved_tickets": 10
          }
        ]
      }
    ]
  }'

Full Request Body Example

{
  "contacts": [
    {
      "customer_external_id": "12345",
      "contact_external_id": "C12345",
      "contact_name": "John Doe",
      "attributes": {
        "email": "example@example.com",
        "phone": "+420 7123 456 789",
        "city": "Brno",
        "age": 35,
        "is_admin": true,
        "last_contacted_at": "2025-04-25"
      },
      "metrics": [
        {
          "date": "2025-04-29",
          "user_status": "active",
          "has_profile_picture": true,
          "resolved_tickets": 39,
          "last_purchase_date": "2024-04-25"
        }
      ]
    }
  ]
}

Attributes Field

The attributes field is an object that contains useful information about a given contact. You can add custom attributes configured in the Customerscore.io application under Attributes Management (opens in a new tab).

Example Attributes Object

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

Supported Value Types

Metrics Field

The metrics field contains product-usage data. It can hold up to 200 items.

Example Metrics Array

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

Processing

Upon successful data import, internal processing will occur. After processing is complete, the contact data will be visible in Customerscore.

Response Codes