Skip to main content

Customerly Destination

Nexla's bi-directional connectors allow data to flow both to and from any location, making it simple to create a FlexFlow data flow that sends data to a Customerly location.
customerly_api.png

Customerly

Create a Customerly Destination​

  1. Click the + icon on the Nexset that will be sent to the Customerly destination, and select the Send to Destination option from the menu.

  2. Select the Customerly connector from the list of available destination connectors. Then, select the credential that will be used to connect to the Customerly workspace, and click Next; or, create a new Customerly credential for use in this flow.

  3. In Nexla, Customerly destinations can be created using pre-built endpoint templates, which expedite destination setup for common Customerly endpoints. Each template is designed specifically for the corresponding Customerly endpoint, making destination configuration easy and efficient.
    • To configure this destination using a template, follow the instructions in Configure Using a Template.

    Customerly destinations can also be configured manually, allowing you to send data to Customerly endpoints not included in the pre-built templates or apply further customizations to exactly suit your needs.
    • To configure this destination manually, follow the instructions in Configure Manually.

Configure Using a Template​

Nexla provides pre-built templates that can be used to rapidly configure destinations to send data to common Customerly endpoints. Each template is designed specifically for the corresponding Customerly endpoint, making destination setup easy and efficient.

  • To configure this destination using a template, select the endpoint to which data will be sent from the Endpoint pulldown menu. Then, click on the template in the list below to expand it, and follow the instructions to configure additional endpoint settings.

    Create User

    Creates a new user in your Customerly workspace. Use this endpoint to push identified user records from external systems — such as your application database, CRM, or data warehouse — into Customerly as tracked users.

    • This endpoint sends the Nexset record payload as a JSON body via HTTP POST to https://api.customerly.io/v1/users.

    • The JSON payload should include the following fields:

      • user_id (required): Your internal identifier for the user. This is used by Customerly to uniquely identify users across your product.
      • email: The user's email address.
      • name: The user's full name.
      • attributes: An object containing any custom user attributes you want to associate with the user in Customerly.
    • No additional template parameters are required. Map your Nexset fields to the appropriate JSON properties using Nexla's data transformation features before sending to this destination.

    If a user with the given user_id already exists in Customerly, the API will update the existing user record rather than creating a duplicate. This makes the Create User endpoint suitable for upsert operations.

    Delete User by ID

    Deletes a user from your Customerly workspace by their user ID. Use this endpoint when you need to remove users from Customerly as part of an automated data lifecycle or compliance workflow.

    • Enter the unique identifier of the user to delete in the User ID field. This is a required parameter.

      • The default value is {'{'}{'{'}}user_id{'}'}{'}'} — map this to the appropriate field in your Nexset if your records use a different field name for the user identifier.
      • The user ID is appended as a query parameter to the DELETE request URL.

    Deleting a user from Customerly is a permanent action. Ensure that the user ID values in your Nexset correspond to the correct Customerly users before activating this destination.

    Unsubscribe User

    Marks a user as unsubscribed from messaging in Customerly, preventing future automated messages from being sent to them. Use this endpoint to honor unsubscribe requests or sync opt-out status from an external suppression list.

    • Enter the unique identifier of the user to unsubscribe in the User ID field. This is a required parameter.

      • The default value is {'{'}{'{'}}user_id{'}'}{'}'} — map this to the appropriate field in your Nexset if your records use a different field name for the user identifier.
      • The user ID is included in the POST request URL path.

    Unsubscribing a user suppresses automated campaign messages but does not prevent manual messages sent by support agents. This is suitable for managing marketing communication preferences.

    Add User to Company

    Associates an existing Customerly user with a company record. Use this endpoint when you need to link users to their organizations based on company data from an external CRM or database.

    • This endpoint sends a JSON body containing the user-to-company mapping via HTTP POST to https://api.customerly.io/v1/users/add-to-company.

    • The JSON payload should include the following fields:

      • user_id (required): The unique identifier of the user to associate.
      • company_id (required): The unique identifier of the company to associate the user with.
    • No additional template parameters are required. Map your Nexset fields to the appropriate JSON properties before sending to this destination.

    Both the user and the company must already exist in Customerly before using this endpoint. If the company does not exist, create it first using the Customerly API before running this association flow.

    Add User Attributes

    Adds or updates custom attributes on a Customerly user. Use this endpoint to enrich user profiles with data from external systems, such as subscription tier, product usage metrics, or account health scores.

    • Enter the unique identifier of the user to update in the User ID field. This is a required parameter.

      • The default value is {'{'}{'{'}}user_id{'}'}{'}'} — map this to the appropriate field in your Nexset if your records use a different field name for the user identifier.
      • The user ID is included in the POST request URL path.
    • The request body should contain a JSON object with the attributes to set or update on the user. Each key-value pair in the body corresponds to a custom attribute name and its new value.

    Custom attributes must be defined in your Customerly workspace before they can be set via the API. Refer to the Customerly settings for managing your attribute definitions.

    Create Lead

    Creates a new lead in your Customerly workspace. Use this endpoint to push anonymous or pre-identified visitor records from external systems into Customerly for tracking and engagement.

    • This endpoint sends the Nexset record payload as a JSON body via HTTP POST to https://api.customerly.io/v1/leads.

    • The JSON payload should include the following fields:

      • email: The lead's email address.
      • name: The lead's full name.
      • attributes: An object containing any custom lead attributes to associate with this record.
    • No additional template parameters are required. Map your Nexset fields to the appropriate JSON properties before sending to this destination.

    Leads are distinct from users in Customerly. Use this endpoint for pre-conversion contacts. Once a lead is identified or converts, they can be promoted to a user using the Create User endpoint.

    Delete Lead by Email

    Deletes a lead from your Customerly workspace by their email address. Use this endpoint to remove leads as part of an automated data hygiene or GDPR compliance workflow.

    • Enter the email address of the lead to delete in the Email field. This is a required parameter.

      • The default value is {'{'}{'{'}}email{'}'}{'}'} — map this to the appropriate field in your Nexset if your records use a different field name for the email address.
      • The email address is appended as a query parameter to the DELETE request URL.

    Deleting a lead from Customerly is a permanent action. Verify that the email values in your Nexset correspond to the correct Customerly leads before activating this destination.

    Create Tag

    Creates a new tag in your Customerly workspace and optionally assigns it to specified users or leads. Use this endpoint to programmatically manage your contact segmentation taxonomy.

    • This endpoint sends the Nexset record payload as a JSON body via HTTP POST to https://api.customerly.io/v1/tags.

    • The JSON payload should include the following fields:

      • name (required): The name of the tag to create.
      • user_ids (optional): An array of user IDs to assign the tag to immediately upon creation.
      • lead_ids (optional): An array of lead IDs to assign the tag to immediately upon creation.
    • No additional template parameters are required. Map your Nexset fields to the appropriate JSON properties before sending to this destination.

    Tag names must be unique within your Customerly workspace. Attempting to create a tag with a name that already exists may result in an error or a duplicate entry, depending on your workspace configuration.

    Delete Tag

    Deletes a tag from your Customerly workspace. Use this endpoint to remove obsolete or unused tags as part of an automated workspace maintenance workflow.

    • This endpoint sends a JSON body containing the tag name via HTTP DELETE to https://api.customerly.io/v1/tags.

    • The JSON payload should include the following field:

      • name (required): The name of the tag to delete.
    • No additional template parameters are required. Map your Nexset field containing the tag name to the appropriate JSON property before sending to this destination.

    Deleting a tag removes it from all users and leads it was previously assigned to. This action is permanent and cannot be undone.

    Send Message to User

    Sends a message to a Customerly user. Use this endpoint to trigger personalized in-app or email messages programmatically based on user behavior, data events, or external system triggers.

    • This endpoint sends the Nexset record payload as a JSON body via HTTP POST to https://api.customerly.io/v1/messages.

    • The JSON payload should include the following fields:

      • user_id (required): The unique identifier of the user who will receive the message.
      • content (required): The message body text.
      • type (required): The message type — for example, chat for in-app messages or email for email messages.
    • No additional template parameters are required. Map your Nexset fields to the appropriate JSON properties before sending to this destination.

    Messages sent via the API are delivered on behalf of your Customerly workspace. The message will appear in the user's conversation thread and in the Customerly inbox. Ensure that the user is not unsubscribed before sending, as messages to unsubscribed users may not be delivered.

    Create Knowledge Base Collection

    Creates a new knowledge base collection in your Customerly workspace. Use this endpoint to programmatically build or replicate your knowledge base structure from an external content management system.

    • This endpoint sends the Nexset record payload as a JSON body via HTTP POST to https://api.customerly.io/v1/knowledge/collections.

    • The JSON payload should include the following fields:

      • title (required): The display title of the collection.
      • description: A brief description of the collection's content.
      • icon: An emoji or icon identifier for the collection.
      • slug: A URL-friendly identifier for the collection.
    • No additional template parameters are required. Map your Nexset fields to the appropriate JSON properties before sending to this destination.

    Collection slugs must be unique within your Customerly workspace. If a slug is not provided, Customerly will generate one automatically based on the collection title.

    Update Knowledge Base Collection

    Updates an existing knowledge base collection in your Customerly workspace. Use this endpoint to sync collection metadata changes from an external system into Customerly.

    • Enter the unique identifier of the collection to update in the Collection ID field. This is a required parameter.

      • The default value is {'{'}{'{'}}knowledge_base_collection_id{'}'}{'}'} — map this to the appropriate field in your Nexset.
      • The collection ID is included in the POST request URL path.
    • The request body should contain a JSON object with the collection fields to update. You may send a partial payload containing only the fields you wish to change.

    Collection IDs can be retrieved using the List Knowledge Base Collections data source endpoint. Use the Get Knowledge Base Collection source endpoint to verify the current state of a collection before updating it.

    Delete Knowledge Base Collection

    Deletes a knowledge base collection from your Customerly workspace by its ID. Use this endpoint to remove obsolete collections as part of an automated content lifecycle workflow.

    • Enter the unique identifier of the collection to delete in the Collection ID field. This is a required parameter.

      • The default value is {'{'}{'{'}}knowledge_base_collection_id{'}'}{'}'} — map this to the appropriate field in your Nexset.
      • The collection ID is included in the DELETE request URL path.

    Deleting a collection may also affect the articles within it, depending on your Customerly workspace configuration. Review collection contents before deleting to avoid unintended data loss.

    Create Knowledge Base Article

    Creates a new knowledge base article in your Customerly workspace. Use this endpoint to programmatically publish support content from an external CMS or content pipeline into Customerly.

    • This endpoint sends the Nexset record payload as a JSON body via HTTP POST to https://api.customerly.io/v1/knowledge/articles.

    • The JSON payload should include the following fields:

      • title (required): The display title of the article.
      • body (required): The HTML or plain text content of the article.
      • collection_id (required): The ID of the collection this article belongs to.
      • slug: A URL-friendly identifier for the article.
    • No additional template parameters are required. Map your Nexset fields to the appropriate JSON properties before sending to this destination.

    Article slugs must be unique within your Customerly workspace. If a slug is not provided, Customerly will generate one automatically based on the article title. Use the List Knowledge Base Collections source endpoint to retrieve valid collection IDs.

    Update Knowledge Base Article

    Updates an existing knowledge base article in your Customerly workspace. Use this endpoint to sync article content changes from an external content management system into Customerly.

    • Enter the unique identifier of the article to update in the Article ID field. This is a required parameter.

      • The default value is {'{'}{'{'}}knowledge_base_article_id{'}'}{'}'} — map this to the appropriate field in your Nexset.
      • The article ID is included in the POST request URL path.
    • The request body should contain a JSON object with the article fields to update. You may send a partial payload containing only the fields you wish to change.

    Article IDs can be retrieved using the List Knowledge Base Articles data source endpoint. Use the Get Knowledge Base Article source endpoint to verify the current content of an article before updating it.

    Delete Knowledge Base Article

    Deletes a knowledge base article from your Customerly workspace by its ID. Use this endpoint to remove outdated or incorrect content as part of an automated knowledge base maintenance workflow.

    • Enter the unique identifier of the article to delete in the Article ID field. This is a required parameter.

      • The default value is {'{'}{'{'}}knowledge_base_article_id{'}'}{'}'} — map this to the appropriate field in your Nexset.
      • The article ID is included in the DELETE request URL path.

    Deleting a knowledge base article is a permanent action and cannot be undone. Verify that the article ID values in your Nexset correspond to the correct articles before activating this destination.

    Add Company Attributes

    Adds or updates custom attributes on a Customerly company record. Use this endpoint to enrich company profiles with data from external systems, such as industry, revenue, or account health scores.

    • Enter the unique identifier of the company to update in the Company ID field. This is a required parameter.

      • The default value is {'{'}{'{'}}company_id{'}'}{'}'} — map this to the appropriate field in your Nexset.
      • The company ID is included in the POST request URL path.
    • The request body should contain a JSON object with the attributes to set or update on the company. Each key-value pair corresponds to a custom attribute name and its new value.

    Custom company attributes must be defined in your Customerly workspace before they can be set via the API. Refer to the Customerly settings for managing your company attribute definitions.

Configure Manually​

Customerly destinations can be manually configured to send data to any valid Customerly API endpoint.

Using manual configuration, you can also configure Nexla to automatically send the response received from the Customerly API after each call to a new Nexla webhook data source.

API Method​

  1. To manually configure this destination, select the Advanced tab at the top of the configuration screen.

  2. Select the API method that will be used for calls to the Customerly API from the Method pulldown menu. Common methods for Customerly write operations include POST (for creating records or sending messages), DELETE (for removing records), and PUT or PATCH (for updates where supported).

Data Format​

  1. Select the format in which the Nexset data will be sent to the Customerly API from the Content Format pulldown menu. Nexla will automatically convert the data to the selected format for each API call. The Customerly API accepts JSON (application/json) for all write operations.

API Endpoint URL​

  1. Enter the URL of the Customerly API endpoint to which you want to send the Nexset data in the URL field. The Customerly REST API base URL is https://api.customerly.io/v1/, followed by the resource path. For update or delete operations that target a specific record, include the record's ID at the end of the URL path (for example, https://api.customerly.io/v1/knowledge/articles/12345).

Request Headers​

Optional

  • If Nexla should include any additional request headers in API calls to this destination, enter the headers & corresponding values as comma-separated pairs in the Request Headers field (e.g., header1:value1,header2:value2).

    You do not need to include the Authentication header — Nexla automatically includes your Customerly Bearer token from the configured credential in all API requests.

Exclude Attributes from the Call​

Optional

  • If any record attributes in the Nexset should be omitted when sending data to this Customerly destination, select the attributes from the Exclude Attributes pulldown menu.

  • Any number of attributes can be selected for exclusion, and all excluded attributes will be shown in the field. To remove an attribute from the list, click the X icon next to the attribute name.

Record Batching​

Optional

  1. If records should be sent to this destination in batched API calls, check the box next to Would you like to batch your records together? to enable record batching.

  2. Enter the maximum number of records that should be batched together in a single API call in the Batch Size field. By default, this value is set to 100.

  3. Select the algorithm that will be used to group records into batches from the Grouping Algorithm pulldown menu. The sample request shown in the panel on the right will be updated to reflect the current batching settings.

Most Customerly API write endpoints accept a single record per request. Review the Customerly API documentation to confirm whether batch payloads are supported for the specific endpoint you are using.

Response Webhook​

Optional

Nexla can automatically send the response received from the Customerly API after each call to a new Nexla webhook data source. This option allows you to keep track of the status of each API call and any additional information returned after each call.

  • To enable this option, check the box next to Would you like to process the API response as a Nexla Webhook source?.

Sample Request Payload​

Sample request payloads containing a portion of the Nexset data that will be sent to the Customerly API endpoint based on the current settings are shown in the Sample Payload panel on the right. These samples can be referenced to ensure that the destination and request settings are correctly configured.

  • Click on a sample request payload to expand it and view the complete payload content.
  • Sample payloads are automatically updated with each setting change, making it easy to verify that changes achieve the desired effect.

Endpoint Testing (Manual Configuration)​

After all endpoint settings have been configured, Nexla can send a test payload to the Customerly API to ensure that the destination is configured correctly.

  1. To send a test payload, select the Test button at the top of the Sample Payload panel, and click on a listed sample payload to expand it.

  2. If any modifications to the sample payload are needed, make the necessary changes directly within the sample window.

  3. Click the Send Test Data button at the top of a sample payload to send the test payload to the Customerly API using the current settings.

Save & Activate the Destination​

  • Once all endpoint settings have been configured, click the Done button in the upper right corner of the screen to save and create the destination. To begin sending data to the configured Customerly endpoint, open the destination resource menu, and select Activate.

    The Nexset data will not be sent to the Customerly API until the destination is activated. Destinations can be activated immediately or at a later time, providing full control over data movement.