# Tidio API Documentation > Combine Tidio OpenAPI with the tools you use every day to create advanced workflows. Get collected contacts, their properties and conversations into your CRM, marketing tools, ERP etc. ## Guides - [Enable Tidio OpenAPI](https://developers.tidio.com/docs/openapi-enable.md) - [Authorization](https://developers.tidio.com/docs/openapi-authorization.md) - [Rate Limiting](https://developers.tidio.com/docs/openapi-rate-limiting.md) - [Versioning](https://developers.tidio.com/docs/openapi-versioning.md) - [Errors](https://developers.tidio.com/docs/openapi-errors.md) - [Pagination](https://developers.tidio.com/docs/openapi-pagination.md) - [Debugging](https://developers.tidio.com/docs/openapi-debugging.md) - [Getting started](https://developers.tidio.com/docs/webhooks-introduction.md) - [Webhooks statistics and history](https://developers.tidio.com/docs/webhooks-statistics-and-history.md) - [Structure](https://developers.tidio.com/docs/webhooks-structure.md) - [Signature verification](https://developers.tidio.com/docs/webhooks-signature-verification.md) - [Delivering](https://developers.tidio.com/docs/webhooks-delivering.md) - [Introduction](https://developers.tidio.com/docs/widget-introduction.md) - [Contact Properties](https://developers.tidio.com/docs/widget-contact-properties.md) - [Visitor Identification](https://developers.tidio.com/docs/widget-visitor-identification.md) - [Listeners / Events](https://developers.tidio.com/docs/widget-listeners-events.md) - [Automation Events](https://developers.tidio.com/docs/widget-automation-events.md) - [Other Methods](https://developers.tidio.com/docs/widget-other-methods.md) - [Code Snippets](https://developers.tidio.com/docs/widget-code-snipets.md) - [Tracking an Abandoned Cart](https://developers.tidio.com/docs/widget-abandoned-cart.md) - [Content Security Policy](https://developers.tidio.com/docs/widget-security-policy.md) - [API Call Node Security](https://developers.tidio.com/docs/api-call-node-security.md) ## API Reference - [Get contacts](https://developers.tidio.com/reference/get_contacts.md): 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. - [Create contact](https://developers.tidio.com/reference/post_contacts.md): 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 use OpenAPI to create a new contact. When creating a contact, you need to provide at least one of the following: `email`, `first_name`, `last_name`, or `phone`. Please note that using this method will always add new contacts. No data will be overwritten, even if it includes the `email` or a `distinct_id`. - [Create multiple contacts](https://developers.tidio.com/reference/post_contacts-batch.md): The same as `[POST] /contacts`, but for multiple contacts. Contacts are saved with `all or nothing` strategy, so all contacts must be valid. The maximum amount of contacts to create in a single request is 100. - [Update multiple contacts](https://developers.tidio.com/reference/patch_contacts-batch.md): The same as `[PATCH] /contacts/{contactId}`, but for multiple contacts. Contacts are saved with `all or nothing` strategy, so all contacts must be valid. The maximum amount of contacts to update in a single request is 100. It is important to note that contacts are website visitors who have interacted with the Tidio widget and have been identified by their name, email address, or phone number. - [Get single contact](https://developers.tidio.com/reference/get_contacts-contactid.md): Each contact has it's own identifier, so on, you can use it to fetch only single specific contact that you need. - [Update contact properties](https://developers.tidio.com/reference/patch_contacts-contactid.md): Each contact in Tidio can have a set of defined properties. It is important to note that contacts are website visitors who have interacted with the Tidio widget and have been identified by their name, email address, or phone number. These properties include `email`, `first_name`, `last_name`, `phone`, `distinct_id`, and `properties`. Each property has a specific type, such as `text`, `email`, `number`, `phone`, or URL. Please note that you can only update contacts that are already [defined in the Tidio panel](https://tidio.com/panel/settings/contact-properties). Pass only the property you want to update. 1. When the property equals null, it is going to be cleared. 2. When a property does not exist in the body, it stays untouched. 3. Passing any non-existing property will result in a validation error. 4. Passing the wrong property type will result in a validation error. - [Delete contact](https://developers.tidio.com/reference/delete_contacts-contactid.md): This API endpoint allows you to delete a specific contact identified by ID. Please be aware that once the contact is deleted, there's no way to recover it, so use this feature with care. - [Get viewed pages history](https://developers.tidio.com/reference/get_contacts-contactid-viewed-pages.md): This resource provides you with a list of pages that the contact has viewed on your website. The list contains entries from the past 30 days. It is important to note that contacts are website visitors who have interacted with the Tidio widget and have been identified by their name, email address, or phone number. - [Get contact properties](https://developers.tidio.com/reference/get_contact-properties.md): The contacts have their properties. In Tidio there are some default properties like `name`, `email`, `phone` etc. and any other properties [that can be defined](https://tidio.com/panel/settings/contact-properties). Each property has a specific type, such as `text`, `email`, `number`, `phone`, or `url`. With this method, you can retrieve the complete list of the properties defined in the Tidio panel. - [Get operators](https://developers.tidio.com/reference/get_operators.md): Operators are chat agents or customer service representatives who interact with customers or website visitors in real-time. They use a chat interface to answer questions, provide support, resolve issues, and guide customers through the purchasing process. In Tidio you can define the operators and set their permissions in [the settings](https://tidio.com/panel/settings/team/operators). You can list the complete list of operators with all it’s properties. - [Get contact messages](https://developers.tidio.com/reference/get_contacts-contactid-messages.md): Contacts may have conversations, which include messages from the contact as well as messages to the contact from chat operators or chatbots. You can list the complete conversation for a particular contact. - [Send a message on behalf of the contact](https://developers.tidio.com/reference/post_contacts-contactid-messages.md): Ingests a message as if the contact had sent it themselves. Used by partners whose end-users type messages into a partner-hosted widget — the partner's backend forwards each message to Tidio via this endpoint. The message is attributed to the contact (not to an operator or bot), persisted into the conversation, routed to the assigned operator's panel like any other inbound message, and triggers any matching bot/AI-agent rules. Processing is asynchronous: the response is `202 Accepted`. Retrieve the persisted message via `GET /contacts/{contactId}/messages` if you need the canonical record. - [Get departments](https://developers.tidio.com/reference/get_departments.md): Departments are teams or groups of operators that handle specific types of customer inquiries or problems. You can use this endpoint to retrieve a complete list of departments, along with their ID and name. Please be aware that the 'General' department is the default option and contains all operators. - [Create ticket (as Contact)](https://developers.tidio.com/reference/post_tickets-as-contact.md): This API endpoint creates a ticket as Contact based on the data provided. - [Get tickets](https://developers.tidio.com/reference/get_tickets.md): Ticket is a record of more complex conversations between operators and customers, which often require additional interactions or cannot be closed in a single chat conversation. It usually also consists of emails and internal messages. This endpoint allows you to retrieve the list of all the tickets with it’s details but without messages. If you need to fetch a particular ticket with its messages, use the Get ticket details endpoint. - [Get ticket details](https://developers.tidio.com/reference/get_tickets-ticketid.md): Ticket is a record of more complex conversations between operators and customers, which often require additional interactions or cannot be closed in a single chat conversation. It usually also consists of emails and internal messages. This endpoint allows you to retrieve all details of a single ticket with messages. - [Update ticket](https://developers.tidio.com/reference/patch_tickets-ticketid.md): This API endpoint allows you to update a specific ticket identified by an ID. This functionality can be used to update parameters such as status, priority or assignment. - [Delete ticket](https://developers.tidio.com/reference/delete_tickets-ticketid.md): This API endpoint allows you to delete a specific ticket identified by ID. This feature can be used to delete requests that are no longer needed or have been resolved. Be careful when using this endpoint. Deleted data is usually irreversible. - [Reply to a ticket](https://developers.tidio.com/reference/post_tickets-ticketid-reply.md): This endpoint allows you to add a reply message to an existing ticket, based on its unique ID. This can be either a message from an operator or from a contact (user). - [Get ticket tags](https://developers.tidio.com/reference/get_tickets-tags.md): Returns the project's tickets tags as a flat list of `{id, name}` objects, sorted alphabetically by `name`. - [Get ticket custom fields](https://developers.tidio.com/reference/get_tickets-custom-fields.md): Returns the project's ticket custom field definitions. - [Ask Lyro to answer ticket](https://developers.tidio.com/reference/post_lyro-tickets.md): This API endpoint asks Lyro to answer a ticket based on the data provided. Responding can take up to 40 seconds. Currently, it only works for the first message in the ticket, which is why the request is limited to a single message. - [Upsert Lyro data source](https://developers.tidio.com/reference/put_lyro-data-sources-website.md): This API endpoint allows you to upload or update a data source for the Lyro AI Agent. Data sources provide knowledge that Lyro uses to answer customer questions. If a data source with the same URL already exists, it will be updated with the new content and title. Otherwise, a new data source will be created. The content should be provided as HTML and will be processed by the Lyro AI Agent. - [Create Lyro QA data source](https://developers.tidio.com/reference/post_lyro-data-sources-qa.md): This API endpoint allows you to create a QA data source for the Lyro AI Agent. Data sources provide knowledge that Lyro uses to answer customer questions. The content should be provided as text and will be processed by the AI Agent. - [Add website as Lyro data source (scraping)](https://developers.tidio.com/reference/post_lyro-data-sources-website-scrape.md): This API endpoint allows you to submit a website URL to be scraped and used as a knowledge data source for the Lyro AI Agent. Each URL must be unique per project. If the URL already exists, a `409 Conflict` response will be returned. - [Get Lyro data sources](https://developers.tidio.com/reference/get_lyro-data-sources.md): Returns a paginated list of data sources used by the Lyro AI Agent. Data sources provide knowledge that Lyro uses to answer customer questions. ## Structure Data sources are organized in a two-level hierarchy based on their `kind`: - **`folder`** – top-level containers grouping scraped or imported QA pairs as children. Includes websites, Zendesk Help Centers articles, PDF files, and more. The `type` field reflects the specific source type (e.g. `website`, `zendesk_hc`). The `content` field is always `null` for folders. Folder items of `type=website` additionally populate `source_url`, `skip_auto_sync`, `manual_sync_available_at`, and `next_auto_sync_at`. - **`qa`** – individual question-answer pairs. Can be: - Standalone (manually created) — `parent_id` is `null` - Children of a folder (scraped/imported) — `parent_id` links to the parent folder's `id` The `content` field is populated for QA items. By default, the list includes both top-level folders and all QA items (including children). Use the `kind` and `parent_id` filters to narrow results. ## Sorting Results are sorted by `updated_at` descending by default. ## Pagination Use the `cursor` value from the `meta` object to fetch the next page. When `meta.cursor` is `null`, there are no more pages. - [Update Lyro QA data source](https://developers.tidio.com/reference/put_lyro-data-sources-qa-id.md): This API endpoint allows you to update an existing QA data source for the Lyro AI Agent. Data sources provide knowledge that Lyro uses to answer customer questions. You must provide the ID of the data source you want to update in the URL. - [Upsert products](https://developers.tidio.com/reference/put_products-batch.md): Upload or update products for Lyro AI recommendations using batch processing. ## Processing - Products are processed in an *all-or-nothing* manner: if any product in the batch is invalid, the entire request fails. - Processing is asynchronous; products become available after a short delay. - Maximum 100 products per request. ## Data Management - A source becomes active after the first product upload. - Push-only model: Tidio does not pull or sync product data from your website automatically. - To update a product, re-send its complete data with the same **id**. - Product entries should represent specific variants (e.g., "Red T-shirt Size M", "Red T-shirt Size S" etc.). ## Requirements - **updated_at** must follow ISO 8601 (e.g., `"2023-06-01T10:00:00+00:00"`). - Field length limits: - **url**: 512 chars - **image_url**: 512 chars - **title**: 512 chars - **vendor**: 255 chars - **product_type**: 255 chars - **sku**: 255 chars - **barcode**: 255 chars - **features** (keys/values): 255 chars each ## Usage Limits - Calling delete on a source in Tidio Panel, removes all its products and requires reupload. This can be done at most 2 times per 24 hours. - Deleting individual products over API does not affect this limit. - [Delete product](https://developers.tidio.com/reference/delete_products-productid.md): Permanently remove a product from Lyro AI recommendations. **Warning:** Product deletion is irreversible and processed asynchronously. **Note:** Individual product deletions do not affect the 24-hour ingestion limit. - [Get project info](https://developers.tidio.com/reference/get_project.md): This endpoint returns information about the authenticated project. - [Webhooks](https://developers.tidio.com/reference/events.md): Webhooks API ## Pages - [Support](https://developers.tidio.com/support.md)