Introduction to the Customerly API

The Customerly API allows you to integrate your platform with Customerly's suite of customer support, marketing automation, and customer satisfaction tools. This document provides an overview of how to authenticate and interact with the API.

Authentication

To interact with the Customerly REST API, you must authenticate your requests using an access token.

Get Access Token

1. Log in to Customerly.
2. Follow the tutorial: How to Obtain Your API Access Token in Customerly.

Using Access Token

Include the access token as a Bearer token in the Authorization header of your HTTP requests:

Authorization: Bearer YOUR_ACCESS_TOKEN

---

Error Handling

When an error occurs, the API returns a JSON response with the following structure:

JSON

{
  "error": {
    "code": "error_code_here",
    "message": "A human-readable error description.",
    "http_status": 400,
    "details": { ... }
  }
}

The details field is optional and provides additional context when available (e.g., validation errors).

Example Error Response

JSON

{
  "error": {
    "code": "auth_missing_authorization_header",
    "message": "The Authorization header is missing.",
    "http_status": 401
  }
}

Error Codes Reference

Below is the complete list of error codes that may be returned by the API:

Code	Description
account_email_not_verified	The account email is not verified.
account_not_found	Account not found.
app_banned	The application is banned.
app_insolvent	The application is insolvent.
app_not_active	The application is not active.
attachment_file_too_large	Attachment file size exceeds the maximum allowed (5MB).
attachment_too_many_files	Too many attachments.
attribute_invalid_format	One or more attributes have invalid format. Attribute names must be alphanumeric (underscores and hyphens allowed), and values must be simple types (strings, numbers, booleans), not arrays or objects.
auth_invalid_access_token	The access token is invalid.
auth_missing_authorization_header	The Authorization header is missing.
company_conflicting_identifiers	The provided identifiers point to different companies. Please provide only one identifier or ensure they all refer to the same company.
company_custom_company_id_required	To create a new company, custom_company_id is required.
company_identifier_required	At least one identifier (company_id or custom_company_id) is required.
company_invalid_filters	The filters are invalid. Check the predicate structure, audience, and condition targets/operations.
company_not_found	Company not found.
contact_cannot_merge_into_itself	A contact cannot be merged into itself. The surviving and victim contacts must be different.
contact_conflicting_identifiers	The provided identifiers point to different contacts. Please provide only one identifier or ensure they all refer to the same contact.
contact_identifier_required	At least one identifier (user_id, email, custom_contact_id, or whatsapp_number) is required.
contact_invalid_filters	The filters are invalid. Check the predicate structure, audience, and condition targets/operations.
contact_is_spam	Cannot send messages from contacts marked as spam.
contact_merge_conflict	One of the contacts is already involved in an ongoing merge, or has already been merged into another contact. Wait for any pending merge to complete before retrying.
contact_not_found	Contact not found.
conversation_access_denied	Access to this conversation is denied.
conversation_assigned_to_ai	Cannot reply to a conversation assigned to AI. The conversation must be assigned to a human account first.
conversation_channel_not_supported	Cannot reply to this conversation channel. Only email and in_app channels support replies via API.
conversation_email_channel_not_supported	The email channel is not supported for conversation messages. You should verify domain to send email.
conversation_frozen	This conversation has been frozen and cannot accept new messages.
conversation_missing_content_or_attachments	Either content or attachments must be provided for the conversation message.
conversation_not_found	The conversation was not found.
conversation_not_open_for_snooze	Only open conversations can be snoozed.
message_range_invalid_order	to must be greater than or equal to from.
message_range_exceeded	The range between from and to exceeds the maximum allowed window.
document_not_found	The document was not found.
document_currently_processing	The document is currently being processed and cannot be modified.
document_file_required	A file is required for upload.
document_file_invalid	The uploaded file is invalid.
document_file_too_large	The file size exceeds the maximum allowed (100MB).
document_file_type_not_allowed	Invalid file type. Only PDF, Word and TXT documents are allowed.
document_conflicting_identifiers	Cannot specify both document_id and custom_document_id at the same time.
document_folder_not_found	The document folder was not found.
document_folder_parent_not_found	The parent folder was not found.
document_folder_destination_not_found	The destination folder was not found.
document_folder_already_exists	A document folder with this name or custom folder ID already exists.
document_folder_invalid_parent	The parent folder is invalid. Only root folders (without a parent) can be used as a parent.
document_folder_conflicting_identifiers	Cannot specify both folder_id and custom_folder_id at the same time.
document_folder_conflicting_folder_identifiers	Cannot specify both folder_id and polymorphic_folder_id at the same time.
event_invalid_format	The event name is invalid. Event names must be alphanumeric (letters, numbers, and underscores only), cannot be empty, and cannot use the reserved prefix "customerly_".
knowledge_base_collection_not_found	The knowledge base collection was not found.
knowledge_base_invalid_locale	The provided locale is invalid.
knowledge_base_locale_not_in_settings	The locale is not configured in knowledge base settings.
knowledge_base_slug_conflict	A collection or article with this slug already exists in this locale/collection.
knowledge_base_multi_locale_forbidden	Multi-locale feature is not available on your plan.
knowledge_base_parent_locale_mismatch	Parent collection must be in the same locale as the child collection.
knowledge_base_parent_too_deep	Collections can only be nested up to 2 levels deep. The parent collection already has a parent.
knowledge_base_parent_missing_linked_locales	The new parent collection does not have linked collections for all the locales of the child linked collections.
knowledge_base_article_not_found	The knowledge base article was not found.
knowledge_base_invalid_status	Status must be 0 (draft) or 1 (published).
knowledge_base_invalid_writer	The writer account ID is invalid.
knowledge_base_writer_not_in_app	The writer must be a valid account in your app.
permission_denied	You don't have permission to perform this action.
request_conflict	Conflict.
request_forbidden	Forbidden.
request_length_required	Length required.
request_locked	Locked.
request_method_not_allowed	Method not allowed.
request_not_acceptable	Not acceptable.
request_not_found	Not found.
request_not_valid	The request is not valid.
request_invalid_json	The request body contains invalid JSON.
request_body_must_be_object	The request body must be a JSON object.
request_payment_required	Payment required.
request_too_many_requests	Too many requests.
request_unauthorized	Unauthorized.
request_unprocessable	Unprocessable entity.
segment_not_found	Segment not found.
segment_invalid_filters	The filters are invalid. Check the predicate structure, audience, and condition targets/operations.
segment_circular_dependency	The segment cannot be saved: a circular dependency was detected between segments.
segment_deletion_in_progress	The segment is already being deleted.
segment_used_as_filter	The segment cannot be deleted because it is used as a filter in other segments, workflows, surveys, or automations. Remove the dependencies first.
server_internal_error	An internal server error occurred, please try again later.
team_not_found	Team not found.
validation_field_required	This field is required.
validation_invalid_email	The email address is invalid.
validation_invalid_length	The field length is invalid.
validation_invalid_type	The field type is invalid.
validation_invalid_value	The field value is invalid.
validation_invalid_whatsapp_number	The WhatsApp number is invalid. It must be in the format [phone].
validation_invalid_user_include_parameter	The user include parameter is invalid. Valid options are: events, companies, segments, notes.