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

Log in to Customerly.
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:

{
  "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

{
  "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 +123456789.
`validation_invalid_user_include_parameter`	The user include parameter is invalid. Valid options are: events, companies, segments, notes.

200Contacts segment found