curl --request GET \
--url https://{your-subdomain}.neetochat.com/api/external/v2/visitors \
--header 'Accept: <accept>' \
--header 'X-Api-Key: <x-api-key>'const options = {method: 'GET', headers: {'X-Api-Key': '<x-api-key>', Accept: '<accept>'}};
fetch('https://{your-subdomain}.neetochat.com/api/external/v2/visitors', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://{your-subdomain}.neetochat.com/api/external/v2/visitors"
headers = {
"X-Api-Key": "<x-api-key>",
"Accept": "<accept>"
}
response = requests.get(url, headers=headers)
print(response.text){
"contacts": [
{
"id": "2c79a334-0bc8-44e4-9504-331f59d400ab",
"name": "Sam Brown",
"email": "sam@example.com",
"phone_number": "+14155550123",
"user_identifier": "customer-1042",
"traits": {
"plan": "Pro"
},
"created_at": "2026-10-08T14:35:46.785Z",
"updated_at": "2026-10-08T14:35:46.785Z",
"field_values": [
{
"field_id": "bac73249-2ef5-46f6-b80d-78271914c2a6",
"field_name": "Plan tier",
"value": "Enterprise"
}
]
}
],
"pagination": {
"current_page": 1,
"total_pages": 4,
"total_count": 52,
"per_page": 15
}
}{
"error": "email and user_identifier must be strings."
}List contacts
List contacts in the workspace, oldest first. Contacts created at the same time are ordered by id.
Filter by email or user_identifier to find the contacts for a person. Neither value is unique in a workspace: the chat widget creates a separate contact for each browser a person chats from, so one person can have several contacts with the same email. These filters therefore return a list, which can contain more than one contact.
curl --request GET \
--url https://{your-subdomain}.neetochat.com/api/external/v2/visitors \
--header 'Accept: <accept>' \
--header 'X-Api-Key: <x-api-key>'const options = {method: 'GET', headers: {'X-Api-Key': '<x-api-key>', Accept: '<accept>'}};
fetch('https://{your-subdomain}.neetochat.com/api/external/v2/visitors', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://{your-subdomain}.neetochat.com/api/external/v2/visitors"
headers = {
"X-Api-Key": "<x-api-key>",
"Accept": "<accept>"
}
response = requests.get(url, headers=headers)
print(response.text){
"contacts": [
{
"id": "2c79a334-0bc8-44e4-9504-331f59d400ab",
"name": "Sam Brown",
"email": "sam@example.com",
"phone_number": "+14155550123",
"user_identifier": "customer-1042",
"traits": {
"plan": "Pro"
},
"created_at": "2026-10-08T14:35:46.785Z",
"updated_at": "2026-10-08T14:35:46.785Z",
"field_values": [
{
"field_id": "bac73249-2ef5-46f6-b80d-78271914c2a6",
"field_name": "Plan tier",
"value": "Enterprise"
}
]
}
],
"pagination": {
"current_page": 1,
"total_pages": 4,
"total_count": 52,
"per_page": 15
}
}{
"error": "email and user_identifier must be strings."
}{your-subdomain} with your workspace’s subdomain. Learn how to find your subdomain in Workspace subdomain.
Headers
Use the X-Api-Key header to provide your workspace API key. Refer to Authentication for more information.
Specifies the expected response format. Must be set to application/json for proper API communication.
application/json Query Parameters
Return only contacts with this email. The match ignores case.
"sam@example.com"
Return only contacts with this user_identifier. When combined with email, a contact must match both.
"customer-1042"
Page number to retrieve, starting from 1. Defaults to 1 when omitted.
1
Number of records per page. Defaults to 15 when omitted, and values above 100 are capped at 100. page_size is accepted as an alias.
15
Response
OK - Request succeeded. contacts is empty when no contact matches the filters.
Hide child attributes
Hide child attributes
"2c79a334-0bc8-44e4-9504-331f59d400ab"
"Sam Brown"
"sam@example.com"
"+14155550123"
Your own identifier for the contact.
"customer-1042"
Custom attributes stored on the contact.
{ "plan": "Pro" }
"2026-10-08T14:35:46.785Z"
"2026-10-08T14:35:46.785Z"
Values the contact holds for the workspace's contact fields. Fields without a value are left out.
Hide child attributes
Hide child attributes
Id of the contact field.
"bac73249-2ef5-46f6-b80d-78271914c2a6"
Name of the contact field.
"Plan tier"
Value stored for the field. Its type depends on the kind of field, such as a string for a text field or an array for a multi-option field.
"Enterprise"