# Customerly Documentation > Documentation for Customerly ## API Reference: Customerly API - [Introduction to the Customerly API](https://customerly.readme.io/reference/intro-to-the-customerly-api.md) - Companies - [Get all contacts for a specific company with pagination](https://customerly.readme.io/reference/get_officialcustomerly_apipublic_v2_companies_companiescontacts_getcontacts.md): Returns a paginated list of contacts (users and leads) associated with a specific company. This endpoint is useful when a company has many contacts, and you want to retrieve them efficiently. ###… - [Get all companies with pagination](https://customerly.readme.io/reference/get_officialcustomerly_apipublic_v2_companies_companies_getcompanies.md): Returns a paginated list of companies for your app. ### Pagination This endpoint uses **offset-based pagination**: - `per_page`: Number of companies to return per page (default: 20, max: 100) -… - [Create or update a company (upsert)](https://customerly.readme.io/reference/post_officialcustomerly_apipublic_v2_companies_companies_upsertcompany.md): Creates a new company or updates an existing one based on the provided identifiers. This endpoint is idempotent and will never create duplicates. ### How It Works - If a company exists (based on… - [Get a company by id or custom company id](https://customerly.readme.io/reference/get_officialcustomerly_apipublic_v2_companies_companies_getcompany.md): Retrieves detailed information about a specific company using either the internal Customerly company ID or your custom identifier. This is the primary way to fetch a single company's complete… - [Delete a company permanently](https://customerly.readme.io/reference/delete_officialcustomerly_apipublic_v2_companies_companies_deletecompany.md): Permanently removes a company from your Customerly account. This action is **irreversible** and will delete the company and all associated data. ⚠️ **Warning**: This action cannot be undone. Make… - [Get all segments for a company with pagination](https://customerly.readme.io/reference/get_officialcustomerly_apipublic_v2_companies_companiessegments_getcompanysegments.md): Returns a paginated list of segments that a company belongs to. ### Company Identification You can retrieve segments using two types of identifiers: **1. Customerly Company ID** (numeric): - Use… - [Batch create or update companies (upsert)](https://customerly.readme.io/reference/post_officialcustomerly_apipublic_v2_companies_companies_upsertcompaniesbatch.md): Creates or updates multiple companies in a single request. This endpoint processes up to 100 companies and returns detailed results for each operation, including successes and failures. ### How It… - [Filter companies with a predicate](https://customerly.readme.io/reference/post_officialcustomerly_apipublic_v2_companies_companiesfilter_filtercompanies.md): Returns a paginated list of the companies matching an arbitrary predicate tree — the same engine that powers companies segments, but evaluated on the fly without having to create a segment first.… - [Count the companies matching a predicate](https://customerly.readme.io/reference/post_officialcustomerly_apipublic_v2_companies_companiesfilter_countcompanies.md): Returns how many companies match a predicate tree, without returning the companies themselves. Useful to preview the size of an audience before paging through `POST /companies/filter`, or before… - Contacts - [Update contact attributes](https://customerly.readme.io/reference/patch_officialcustomerly_apipublic_v2_contacts_contactsattributes_updatecontactattributes.md): Updates or adds custom attributes to an existing contact. Attributes are merged with existing ones. ### Polymorphic ID formats - Numeric ID: `29911301` - Custom User ID: `cuid:user_123` - Custom… - [Get all companies for a contact with pagination](https://customerly.readme.io/reference/get_officialcustomerly_apipublic_v2_contacts_contactscompanies_getcontactcompanies.md): Returns a paginated list of companies that a contact is associated with. ### Contact Identification You can retrieve companies using various types of identifiers: **1. Customerly Contact ID**… - [Add a contact to a company](https://customerly.readme.io/reference/put_officialcustomerly_apipublic_v2_contacts_contactscompanies_addcontacttocompany.md): Associates a contact with a company. If the company doesn't exist and you provide a custom company ID (with `cid:` prefix), it will be automatically created. ### How to Identify the Contact Use any… - [Remove a contact from a company](https://customerly.readme.io/reference/delete_officialcustomerly_apipublic_v2_contacts_contactscompanies_removecontactfromcompany.md): Removes the association between a contact and a company. The contact and company themselves are not deleted, only the relationship between them is removed. ### How to Identify the Contact Use any of… - [List all contacts with pagination and filtering](https://customerly.readme.io/reference/get_officialcustomerly_apipublic_v2_contacts_contacts_listcontacts.md): Retrieves a paginated list of your contacts (both users and leads). This endpoint supports filtering, searching, and sorting to help you find the contacts you need. ### What is a Contact? A contact… - [Create or update a contact (upsert)](https://customerly.readme.io/reference/post_officialcustomerly_apipublic_v2_contacts_contacts_upsertcontact.md): Creates a new contact or updates an existing one based on the provided identifiers. This endpoint intelligently handles conflicts and merges data according to specified rules. ### How Identifiers… - [Get a single contact by ID](https://customerly.readme.io/reference/get_officialcustomerly_apipublic_v2_contacts_contacts_getcontact.md): Retrieves detailed information about a specific contact using various types of identifiers. This is the primary way to fetch a single contact's complete profile. ### How to Identify a Contact You… - [Delete a contact permanently](https://customerly.readme.io/reference/delete_officialcustomerly_apipublic_v2_contacts_contacts_deletecontact.md): Permanently removes a contact from your Customerly account. This action is **irreversible** and will delete all associated data including: - Contact profile and attributes - Conversation history -… - [Batch create or update contacts (upsert)](https://customerly.readme.io/reference/post_officialcustomerly_apipublic_v2_contacts_contacts_upsertcontactsbatch.md): Creates or updates multiple contacts in a single request. This endpoint processes up to 100 contacts and returns detailed results for each operation, including successes and failures. ### How It… - [Get all events for a contact with pagination](https://customerly.readme.io/reference/get_officialcustomerly_apipublic_v2_contacts_contactsevents_getcontactevents.md): Returns a paginated list of events that a contact has triggered. Events are statistical records showing what actions a contact has performed, when they first and last occurred, and how many times… - [Add a note to a contact](https://customerly.readme.io/reference/post_officialcustomerly_apipublic_v2_contacts_contactsnotes_createnote.md): Creates a new internal note for a specific contact. Notes are useful for tracking important information, context, or reminders about contacts that your team needs to remember. ### How to Identify a… - [Get all segments for a contact with pagination](https://customerly.readme.io/reference/get_officialcustomerly_apipublic_v2_contacts_contactssegments_getcontactsegments.md): Returns a paginated list of segments that a contact belongs to. ### Contact Identification You can retrieve segments using various types of identifiers: **1. Customerly Contact ID** (numeric): -… - [Merge two contacts into one](https://customerly.readme.io/reference/post_officialcustomerly_apipublic_v2_contacts_contacts_mergecontacts.md): Merges a **victim** contact into a **surviving** contact. The victim's data (conversations, events, attributes, tags, notes, segments, companies, and analytics) is re-parented to the survivor, and… - [Get a contact's activity timeline with pagination](https://customerly.readme.io/reference/get_officialcustomerly_apipublic_v2_contacts_contactsactivity_getcontactactivitytimeline.md): Returns a paginated, cross-source timeline of everything a contact has done, merged in reverse-chronological order (most recent first): conversations opened, campaigns received, events fired, NPS… - [Filter contacts with a predicate](https://customerly.readme.io/reference/post_officialcustomerly_apipublic_v2_contacts_contactsfilter_filtercontacts.md): Returns a paginated list of the contacts matching an arbitrary predicate tree — the same engine that powers segments, but evaluated on the fly without having to create a segment first. Use `GET… - [Count the contacts matching a predicate](https://customerly.readme.io/reference/post_officialcustomerly_apipublic_v2_contacts_contactsfilter_countcontacts.md): Returns how many contacts match a predicate tree, without returning the contacts themselves. Useful to preview the size of an audience before paging through `POST /contacts/filter`, or before… - Conversations - [List conversations with filtering and pagination](https://customerly.readme.io/reference/get_officialcustomerly_apipublic_v2_conversations_list_listall.md): Retrieves conversations from your workspace with powerful filtering capabilities. You can filter by: - **Assignment**: specific teammate (`account_id`) or team (`team_id`) - **Status**: `opened`,… - [Create a new conversation with the first message](https://customerly.readme.io/reference/post_officialcustomerly_apipublic_v2_conversations_conversations_create.md): This endpoint allows you to create a new conversation between a contact and an account, with the first message included. The conversation can be initiated by either party. > **WhatsApp conversations… - [List all inboxes with conversation counts](https://customerly.readme.io/reference/get_officialcustomerly_apipublic_v2_conversations_inbox_getinboxes.md): Retrieves the complete inbox structure for your workspace, organized by **teams**, **individual teammates** and **conversation segments**. Each inbox includes: - `total`: number of conversations… - [Get conversation count for the applied filters](https://customerly.readme.io/reference/get_officialcustomerly_apipublic_v2_conversations_list_stats.md): Returns the total number of conversations matching your filter criteria. This is useful for: - Displaying badge counts in your UI - Building dashboards with conversation metrics - Checking filter… - [List messages in a conversation](https://customerly.readme.io/reference/get_officialcustomerly_apipublic_v2_conversations_messages_listall.md): Retrieves the message history for a specific conversation. Messages include: - Text content and attachments - Sender information (contact, teammate, or bot) - Timestamps and read status Results are… - [Reply to a conversation](https://customerly.readme.io/reference/post_officialcustomerly_apipublic_v2_conversations_messages_create.md): Adds a new message to an existing conversation. The message can be sent by either the contact or an account (team member). > Only `in_app` and `email` conversations can be replied to here. A… - [Get a single conversation by ID](https://customerly.readme.io/reference/get_officialcustomerly_apipublic_v2_conversations_list_getone.md): Retrieves detailed information about a specific conversation, including: - Conversation metadata (status, assignee, tags, timestamps) - Associated contact information - AI assistant interaction… - [Update the status of a conversation](https://customerly.readme.io/reference/patch_officialcustomerly_apipublic_v2_conversations_conversations_updatestatus.md): Change a conversation status to one of: - `opened` — re-opens a previously closed or snoozed conversation - `closed` — closes the conversation (runs CSAT/classification flow when enabled) -… - [Update conversation attributes](https://customerly.readme.io/reference/patch_officialcustomerly_apipublic_v2_conversations_conversationsattributes_updateconversationattributes.md): Updates or adds custom attributes to an existing conversation. Attributes are merged with existing ones. ### Behavior - Attributes are merged incrementally (only specified attributes are updated) -… - [List the topics of a conversation](https://customerly.readme.io/reference/get_officialcustomerly_apipublic_v2_conversations_conversationstopics_listall.md): Returns the topics attached to a conversation, both the ones applied by your team and the ones suggested by the AI assistant. Discarded topics are not returned. Topics are the categories used to… - WhatsApp - [Start a new WhatsApp conversation with a template message.](https://customerly.readme.io/reference/post_officialcustomerly_apipublic_v2_conversations_whatsapptemplates_start.md): Opens a brand new conversation with a contact on WhatsApp and sends an approved template as its first message. This is the only way to reach a contact that never wrote to you, or that has been silent… - [Send a WhatsApp template message to an existing conversation.](https://customerly.readme.io/reference/post_officialcustomerly_apipublic_v2_conversations_whatsapptemplates_sendtoconversation.md): Sends an approved template into a conversation that already runs on WhatsApp. This is the only way to write into a WhatsApp conversation through the API: `POST… - [List the WhatsApp templates available to your project.](https://customerly.readme.io/reference/get_officialcustomerly_apipublic_v2_whatsapp_whatsapptemplates_listall.md): Returns the message templates that were approved by Meta for the WhatsApp Business Accounts (WABA) connected to your project. Templates are the only way to open a conversation with a contact, or to… - Documents - [Get all documents with pagination](https://customerly.readme.io/reference/get_officialcustomerly_apipublic_v2_documents_documents_getdocuments.md): Returns a paginated list of documents for your app. The response excludes the document body to keep the payload lightweight. Use the `GET /documents/{id}` endpoint to retrieve the full document… - [Create or update a document](https://customerly.readme.io/reference/put_officialcustomerly_apipublic_v2_documents_documents_upsertdocument.md): This endpoint performs an upsert operation: it creates a new document or updates an existing one based on the identifier you provide. ### Document Identification You must provide **exactly one** of… - [Get a document by id or custom document id](https://customerly.readme.io/reference/get_officialcustomerly_apipublic_v2_documents_documents_getdocument.md): Retrieves a document using either the internal Customerly document ID or your custom identifier. ### Document Identification You can retrieve a document using two types of identifiers: **1.… - [Delete a document](https://customerly.readme.io/reference/delete_officialcustomerly_apipublic_v2_documents_documents_deletedocument.md): Deletes a document using either the internal Customerly document ID or your custom identifier. If the document is not found, a 404 error is returned. ### Document Identification You can delete a… - [Upload a document file](https://customerly.readme.io/reference/post_officialcustomerly_apipublic_v2_documents_documents_uploaddocument.md): This endpoint performs an upsert operation for document files: it uploads a new document or replaces an existing document's file based on the identifier you provide. ### Document Identification You… - [Get all document folders](https://customerly.readme.io/reference/get_officialcustomerly_apipublic_v2_documents_documentfolders_getfolders.md): Returns a list of all folders used to organize documents. Each folder contains a count of how many documents it contains. - [Create or update a document folder](https://customerly.readme.io/reference/put_officialcustomerly_apipublic_v2_documents_documentfolders_upsertfolder.md): This endpoint performs an upsert operation: it creates a new folder or updates an existing one based on the identifier you provide. ### Folder Identification You must provide **at most one** of the… - [Get a document folder by ID or custom folder ID](https://customerly.readme.io/reference/get_officialcustomerly_apipublic_v2_documents_documentfolders_getfolder.md): Retrieves a folder using either the internal Customerly folder ID or your custom identifier. ### Folder Identification **1. Customerly Folder ID** (numeric): - Example: `GET /documents/folders/10`… - [Delete a document folder](https://customerly.readme.io/reference/delete_officialcustomerly_apipublic_v2_documents_documentfolders_deletefolder.md): Deletes a document folder. Optionally move contained documents to another folder. If no destination is provided, documents inside will have their folder cleared (orphaned). ### Folder Identification… - Knowledge Base - [Retrieve the list of available writers for knowledge base articles](https://customerly.readme.io/reference/get_officialcustomerly_apipublic_v2_knowledgebase_articles_listwriters.md): Returns all **team members** (accounts) who have access to your app and can be assigned as authors of knowledge base articles. Use the `account_id` from this list when creating or updating articles… - [Retrieve a paginated list of knowledge base articles with optional filtering](https://customerly.readme.io/reference/get_officialcustomerly_apipublic_v2_knowledgebase_articles_listarticles.md): Returns articles with support for filtering by collection and publication status. Articles are returned in their **creation order**. Use this endpoint to browse your knowledge base content or to… - [Create or update a knowledge base article](https://customerly.readme.io/reference/put_officialcustomerly_apipublic_v2_knowledgebase_articles_upsertarticle.md): This endpoint performs an **upsert operation**: it creates a new article or updates an existing one based on the `article_id` you provide. ### Article Identification **If `article_id` is… - [Retrieve detailed information about a specific knowledge base article](https://customerly.readme.io/reference/get_officialcustomerly_apipublic_v2_knowledgebase_articles_getarticle.md): Returns **complete article information** including the full HTML body content, collection details, author information, and engagement metrics (visits and reactions). Use this endpoint when you need… - [Delete a knowledge base article](https://customerly.readme.io/reference/delete_officialcustomerly_apipublic_v2_knowledgebase_articles_deletearticle.md): Permanently deletes an article from your knowledge base. ⚠️ **Warning**: This operation cannot be undone. Make sure to backup any content you want to preserve before deletion. **Note**: This… - [Retrieve a paginated list of knowledge base collections for a specific locale](https://customerly.readme.io/reference/get_officialcustomerly_apipublic_v2_knowledgebase_collections_listcollections.md): Returns all collections for the specified `locale`, ordered by their sort position. Collections can be organized in a **hierarchical structure** with parent-child relationships (maximum 2 levels… - [Retrieve detailed information about a specific knowledge base collection](https://customerly.readme.io/reference/get_officialcustomerly_apipublic_v2_knowledgebase_collections_getcollection.md): Returns **complete information** about a collection including its parent collection details if it exists. Use this endpoint when you need full collection metadata including `icon`, `slug`, and `sort`… - [Delete a knowledge base collection](https://customerly.readme.io/reference/delete_officialcustomerly_apipublic_v2_knowledgebase_collections_deletecollection.md): Permanently deletes a collection and all its contents. This operation will: - Delete the collection itself - Delete all articles within the collection - Recursively delete all child collections and… - [Create or update a knowledge base collection](https://customerly.readme.io/reference/put_officialcustomerly_apipublic_v2_knowledgebase_collections_upsertcollection.md): This endpoint performs an **upsert operation**: it creates a new collection or updates an existing one based on the `collection_id` you provide. ### Collection Identification **If `collection_id`… - Messages - [List all messages](https://customerly.readme.io/reference/get_officialcustomerly_apipublic_v2_messages_messages_listall.md): Retrieves all messages across all conversations for the app, using cursor-based pagination. Designed for bulk export — iterate by advancing the `cursor` until `cursor` in the response is `null`. By… - Segments - [List companies segments with pagination](https://customerly.readme.io/reference/get_officialcustomerly_apipublic_v2_segments_companiessegments_list.md): Returns a paginated list of all companies segments defined in your app. Segments are ordered by ID descending (most recently created first). ### Pagination This endpoint uses cursor-based… - [Create or update a companies segment](https://customerly.readme.io/reference/put_officialcustomerly_apipublic_v2_segments_companiessegments_upsert.md): This endpoint performs an **upsert operation**: it creates a new companies segment or updates an existing one based on the `segment_id` you provide. **If `segment_id` is provided**: - The segment… - [Get a single companies segment](https://customerly.readme.io/reference/get_officialcustomerly_apipublic_v2_segments_companiessegments_getone.md): Returns the full definition of a companies segment including its predicate filters. - [Delete a companies segment](https://customerly.readme.io/reference/delete_officialcustomerly_apipublic_v2_segments_companiessegments_delete.md): Permanently deletes a companies segment. The segment must not be used as a filter condition in other segments — remove those dependencies first. Companies that were members of the segment are… - [List contacts segments with pagination](https://customerly.readme.io/reference/get_officialcustomerly_apipublic_v2_segments_contactssegments_list.md): Returns a paginated list of all contacts segments defined in your app. Segments are ordered by ID descending (most recently created first). ### Pagination This endpoint uses cursor-based pagination:… - [Create or update a contacts segment](https://customerly.readme.io/reference/put_officialcustomerly_apipublic_v2_segments_contactssegments_upsert.md): This endpoint performs an **upsert operation**: it creates a new contacts segment or updates an existing one based on the `segment_id` you provide. **If `segment_id` is provided**: - The segment… - [Get a single contacts segment](https://customerly.readme.io/reference/get_officialcustomerly_apipublic_v2_segments_contactssegments_getone.md): Returns the full definition of a contacts segment including its predicate filters. - [Delete a contacts segment](https://customerly.readme.io/reference/delete_officialcustomerly_apipublic_v2_segments_contactssegments_delete.md): Permanently deletes a contacts segment. The segment must not be used as a filter condition in other segments, workflows, surveys, or automations — remove those dependencies first. Contacts that were… - [List conversation segments with pagination](https://customerly.readme.io/reference/get_officialcustomerly_apipublic_v2_segments_conversationssegments_list.md): Returns a paginated list of the conversation segments **visible to your account**. Segments are ordered by ID descending (most recently created first). ### Visibility A conversation segment is… - [Create or update a conversation segment](https://customerly.readme.io/reference/put_officialcustomerly_apipublic_v2_segments_conversationssegments_upsert.md): This endpoint performs an **upsert operation**: it creates a new conversation segment or updates an existing one based on the `segment_id` you provide. **If `segment_id` is provided**: the segment… - [Get a single conversation segment](https://customerly.readme.io/reference/get_officialcustomerly_apipublic_v2_segments_conversationssegments_getone.md): Returns the full definition of a conversation segment including its predicate filters. Returns `404` if the segment does not exist for your app, and `403` if the segment is private and not visible to… - [Delete a conversation segment](https://customerly.readme.io/reference/delete_officialcustomerly_apipublic_v2_segments_conversationssegments_delete.md): Permanently deletes a conversation segment. You must be its creator or a master account. The conversations that matched the segment are **not** deleted. - Tags - [Get all tags](https://customerly.readme.io/reference/get_officiallist.md): Returns a list of all unique tags used in your account across all contacts. - [Apply or remove a tag to/from multiple contacts](https://customerly.readme.io/reference/post_officialcustomerly_apipublic_v2_tags_tags_applytag.md): Add or remove a tag to/from a list of contacts identified by their polymorphic IDs.