Contact upload

Import contact data into Customerscore.io 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.io. Before sending contacts, you must first have the customers stored in Customerscore.io.

Request Body

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

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": "[email protected]",
          "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": "[email protected]",
        "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"
        }
      ]
    }
  ]
}

Batch Size

We strongly recommend sending contacts in batches rather than one by one. Each request can include up to 100 contacts, and the request body is limited to 5 MB.

For best performance and reliability, we recommend:

• 50–100 contacts per request
• Request body size below 5 MB

Batching reduces network overhead and helps you stay within the rate limit. A request with more than 100 contacts is rejected with 400 Bad Request and none of its contacts are imported — split larger datasets into multiple requests.

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": "[email protected]",
  "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"
  }
]

Data Source Precedence

Attributes and metrics are stored regardless of their data source — the API always takes precedence. This includes properties fed by another source (HubSpot, Stripe, a file import, …). Such a property keeps its data source, so the next sync from that source overwrites the value again. A property with no data source yet is assigned the API as its data source.

Values for calculated properties are ignored — they are derived from other values and recalculated automatically. Each ignored key is recorded as a warning on the import, visible under Settings → Imports (opens in a new tab).

Processing

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

Response Codes