Get Contact
Retrieve a single contact by the external IDs you already use to create or update it — the customer's and the contact's.
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}/contact/{contactExternalId} |
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
customerExternalId | string | Yes | External ID of the customer the contact belongs to. |
contactExternalId | string | Yes | Contact external ID. |
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
properties | string | No | Comma-separated contact property codenames to include in the properties object (e.g. job_title,email). Omit to return all. Core fields are always returned. |
Example Request
curl -X GET "https://api.customerscore.io/api/v1/customer/12345/contact/contact-001?properties=job_title,email" \
-H "customerscore-key: your-generated-key"Response Body
| Field | Type | Nullable | Description |
|---|---|---|---|
id | string | No | Contact external ID (the identifier from your system). |
customerscore_id | number | No | Internal CustomerScore ID of the contact record. |
name | string | Yes | Contact name. |
engagementscore | number | Yes | Engagement (health) score. |
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). |
last_seen | string | Yes | Latest scoring date (YYYY-MM-DD). |
tags | string[] | No | Titles of the tags assigned to this contact. Empty array when none. |
customer_external_id | string | Yes | External ID of the customer the contact belongs to. |
customer_customerscore_id | number | Yes | Internal CustomerScore ID of the customer the contact belongs to. |
properties | object | No | Custom contact property values keyed by codename. |
createdAt | string | Yes | When the contact record was created (ISO 8601). |
updatedAt | string | Yes | When the contact record was last updated (ISO 8601). |
Example Response
{
"id": "contact-001",
"customerscore_id": 45678,
"name": "John Doe",
"engagementscore": 72,
"engagementscore_difference": 4,
"engagementscore_trend": {
"2024-06-14": 68,
"2024-06-15": 72
},
"last_seen": "2024-06-15",
"tags": ["Champion"],
"customer_external_id": "12345",
"customer_customerscore_id": 98765,
"properties": {
"job_title": "CTO",
"email": "[email protected]"
},
"createdAt": "2024-01-10T08:30:00.000Z",
"updatedAt": "2024-06-15T09:00:00.000Z"
}Response Codes
| Code | Description |
|---|---|
| 200 | The contact was found and returned |
| 401 | Unauthorized - Missing customerscore-key in the header |
| 403 | Forbidden - Invalid key |
| 404 | Customer or contact not found |
| 405 | Method Not Allowed - Only GET method is allowed |