Get Customer
Retrieve a single customer by the external ID you already use to create or update them.
For interactive API documentation, see the Swagger reference (opens in a new tab).
Endpoint
| Method | URL |
|---|---|
| GET | https://api.customerscore.io/api/v1/customer/{customerExternalId} |
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
customerExternalId | string | Yes | Customer external ID — the same identifier used to create/update. |
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
properties | string | No | Comma-separated custom property codenames to include in the properties object (e.g. mrr,plan). Omit to return all. Core fields are always returned. |
Example Request
curl -X GET "https://api.customerscore.io/api/v1/customer/12345?properties=mrr,plan" \
-H "customerscore-key: your-generated-key"Response Body
| Field | Type | Nullable | Description |
|---|---|---|---|
id | string | No | Customer external ID (the identifier from your system). |
customerscore_id | number | No | Internal CustomerScore ID of the customer record. |
name | string | Yes | Customer name. |
fitscore | number | Yes | Fit score. |
engagementscore | number | Yes | Engagement (health) score. |
churn_risk | number | Yes | Churn risk score. |
is_churned | boolean | Yes | Whether the customer is churned. |
last_seen | string | Yes | Latest scoring date (YYYY-MM-DD). |
engagementscore_difference | number | Yes | Engagement score change since the previous scoring record. |
engagementscore_trend | object | Yes | Engagement score history (last 15 records within 1 year), keyed by scoring date (YYYY-MM-DD). |
owner | string | Yes | Email of the user who owns this customer. null when unassigned. |
tags | string[] | No | Titles of the tags assigned to this customer. Empty array when none. |
properties | object | No | Custom property values keyed by codename. |
createdAt | string | Yes | When the customer record was created (ISO 8601). |
updatedAt | string | Yes | When the customer record was last updated (ISO 8601). |
Example Response
{
"id": "12345",
"customerscore_id": 98765,
"name": "Acme Corporation",
"fitscore": 82,
"engagementscore": 67,
"churn_risk": 18,
"is_churned": false,
"last_seen": "2024-06-15",
"engagementscore_difference": 3,
"engagementscore_trend": {
"2024-06-14": 64,
"2024-06-15": 67
},
"owner": "jane@acme.com",
"tags": ["VIP", "Trial"],
"properties": {
"mrr": 1500,
"plan": "enterprise"
},
"createdAt": "2024-01-10T08:30:00.000Z",
"updatedAt": "2024-06-15T09:00:00.000Z"
}Response Codes
| Code | Description |
|---|---|
| 200 | The customer was found and returned |
| 401 | Unauthorized - Missing customerscore-key in the header |
| 403 | Forbidden - Invalid key |
| 404 | Customer not found |
| 405 | Method Not Allowed - Only GET method is allowed |