---
updatedAt: 2026-06-15T09:50:57.000Z
agentTools:
projectIndex: https://developers.tidio.com/llms.txt
---
# Get contacts
Contacts are site visitors who have interacted with the Tidio widget and have been identified by their name, email address, or phone number.
Each contact can have custom properties that can be given by the contact, added by chat operators, or updated by chatbots. Contacts may also have conversations, which include messages from the contact as well as messages to the contact from chat operators or chatbots.
You can list contacts with all their properties.
# OpenAPI definition
```json
{
"openapi": "3.0.3",
"info": {
"title": "Tidio - Openapi",
"version": "1.0"
},
"servers": [
{
"url": "https://api.tidio.com/"
}
],
"tags": [
{
"name": "Contacts"
}
],
"security": [
{
"ClientId": [],
"ClientSecret": []
}
],
"paths": {
"/contacts": {
"get": {
"tags": [
"Contacts"
],
"summary": "Get contacts",
"description": "Contacts are site visitors who have interacted with the Tidio widget and have been identified by their name, email address, or phone number.\n\nEach contact can have custom properties that can be given by the contact, added by chat operators, or updated by chatbots. Contacts may also have conversations, which include messages from the contact as well as messages to the contact from chat operators or chatbots.\n\nYou can list contacts with all their properties.\n",
"parameters": [
{
"$ref": "#/components/parameters/Cursor"
},
{
"in": "query",
"name": "email",
"schema": {
"type": "string",
"format": "email"
},
"required": false,
"description": "Filter contacts by email address",
"example": "user@tidio.com"
}
],
"responses": {
"200": {
"description": "Paginated list of contacts",
"content": {
"application/json; version=1": {
"schema": {
"allOf": [
{
"type": "object",
"properties": {
"contacts": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ContactResponse"
}
}
}
},
{
"$ref": "#/components/schemas/PaginatedResponse"
}
]
}
}
}
},
"400": {
"$ref": "#/components/responses/PaginationErrorResponse"
}
}
}
}
},
"components": {
"parameters": {
"Cursor": {
"name": "cursor",
"in": "query",
"description": "Value from the previous page. Use null to fetch the first one",
"required": false,
"explode": false,
"schema": {
"type": "string",
"example": "aWRfX2U2YTgyYTc0LTExNzAtNGY1Ny1hMDMxLWIzNmYzZjZiYzA5Mw=="
}
}
},
"schemas": {
"ContactResponse": {
"type": "object",
"properties": {
"id": {
"allOf": [
{
"$ref": "#/components/schemas/ContactID"
}
]
},
"distinct_id": {
"type": "string",
"nullable": true,
"description": "ID of the contact in external system",
"example": "123456"
},
"first_name": {
"type": "string",
"nullable": true,
"description": "First name of the contact",
"example": "John"
},
"last_name": {
"type": "string",
"nullable": true,
"description": "Last name of the contact",
"example": "Doe"
},
"email": {
"type": "string",
"nullable": true,
"description": "Email address of the contact",
"example": "email@example.com",
"format": "email"
},
"phone": {
"type": "string",
"nullable": true,
"description": "Phone number of the contact",
"example": "123 456 789"
},
"language": {
"type": "string",
"nullable": true,
"description": "Language of the contact in ISO 639-1 format (lowercase)",
"example": "en"
},
"country": {
"type": "string",
"nullable": true,
"description": "Country of the contact in ISO 3166 Alpha-2 format (uppercase)",
"example": "US"
},
"city": {
"type": "string",
"nullable": true,
"description": "City of the contact",
"example": "New York"
},
"messenger_id": {
"type": "string",
"nullable": true,
"description": "❗️ Deprecated: it always returns null. Will be removed in the next version.\n\nMessenger ID of the contact\n",
"example": null,
"deprecated": true
},
"instagram_id": {
"type": "string",
"nullable": true,
"description": "❗️ Deprecated: it always returns null. Will be removed in the next version.\n\nInstagram ID of the contact\n",
"example": null,
"deprecated": true
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Creation date of the contact",
"example": "2023-01-01T00:00:00+00:00"
},
"email_consent": {
"type": "string",
"nullable": true,
"enum": [
"subscribed",
"unsubscribed"
],
"description": "This field indicates if contact agreed to newsletter subscription",
"example": "subscribed"
},
"properties": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ContactProperty"
}
}
}
},
"ContactProperty": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Contact property name",
"example": "shoe_size",
"maxLength": 128
},
"value": {
"type": "string",
"description": "Contact property value",
"example": "44 (EU)",
"maxLength": 1000
}
}
},
"Meta": {
"type": "object",
"properties": {
"cursor": {
"type": "string",
"nullable": true,
"description": "Value to fetch the next page. Null means the page is the last one.",
"example": "aWRfX2U2YTgyYTc0LTExNzAtNGY1Ny1hMDMxLWIzNmYzZjZiYzA5Mw=="
},
"limit": {
"type": "integer",
"description": "How many items were displayed on list",
"example": 1000
}
}
},
"Error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"example": "bad_request",
"title": "Error code"
},
"message": {
"type": "string",
"title": "More specific description of the error",
"example": "The request was invalid or cannot be served. "
}
}
},
"ErrorResponse": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"PaginatedResponse": {
"type": "object",
"properties": {
"meta": {
"$ref": "#/components/schemas/Meta"
}
}
},
"ContactID": {
"type": "string",
"format": "uuid",
"description": "ID of the contact",
"example": "a1b4ca4c-1108-4432-b256-1e4cf2bf6f9e"
}
},
"securitySchemes": {
"ClientId": {
"type": "apiKey",
"in": "header",
"name": "X-Tidio-Openapi-Client-Id"
},
"ClientSecret": {
"type": "apiKey",
"in": "header",
"name": "X-Tidio-Openapi-Client-Secret"
}
},
"responses": {
"PaginationErrorResponse": {
"description": "Invalid cursor",
"content": {
"application/json; version=1": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"code": "invalid_cursor",
"message": "Cursor is invalid"
}
]
}
}
}
}
}
}
}
```