You can export behavior, marketing, consent and form signals from Connect to CSV. The file is compressed into a gzip archive and uploaded to a secure SFTP directory allocated to your Connect subscription.

Running the mutation

If you haven't used our API before, see Using the Connect API for instructions. It explains how to authenticate your calls and suggests some tools for testing.

Daily usage limits

Total data jobs: 20
Total output size: 1GB
Total rows unloaded: 2 million

If any of these limits is reached, the export operation becomes unavailable for the day.

Basic mutation structure

mutation {
  exportSignals(
    jobName: "July Email Engagement Export"
    export: {
      signals: {
        signalTypes: ["emailOpen", "emailClick", "emailDelivery"]
        timestampStart: "2025-07-01T00:00:00.000Z"
        timestampEnd: "2025-07-31T23:59:59.999Z"
      }
    }
    notifications: [{ channel: EMAIL, destination: "[email protected]" }]
  ) {
    dataJobId
    path
    fileFormat
  }
}

Mutation arguments

Argument	Type	Required?	Description
`export`	Object	Required	Signal types and date range (see Export object below)
`jobName`	String	Required	Unique name for the export job
`notifications`	Array of objects	Optional	Recipients for completion notifications
`to`	Object	Optional	Custom target directory and file naming

Export object

The export field contains the signals object with these required fields:

Signals object

signalTypes(optional): Array of strings - The signal types to export (see Signal types below). If you omit it, Connect exports every signal type that's available for export in your subscription.
timestampStart(required): DateTime string - Start of export period (ISO 8601, with milliseconds)
timestampEnd(required): DateTime string - End of the export period (ISO 8601, with milliseconds). The period must be longer than 0 and no longer than 365 days.
suppressPiiFields (optional): Boolean - Excludes personally identifiable information from the export (default: false).

Implementation notes

The suppressPiiFields parameter applies to all signal types in the export
When enabled, it affects contact data columns but preserves the CSV structure
The suppression happens at export time, not at signal storage
DATASET_ID is intentionally never suppressed to maintain traceability

PII suppression (optional)

The suppressPiiFields parameter (Boolean, default: false) controls whether personally identifiable information is included in the export. When set to true:

Audience attributes with category Contact information are set to NULL
Audience attributes with non-empty identifyAs.channels (addressable fields) are set to NULL
Consent fields (CONSENT_EMAIL, CONSENT_SMS, CONSENT_WHATSAPP, CONSENT_MOBILE) are set to NULL
DATASET_ID is never suppressed
Non-PII attributes (custom fields, behavioral attributes) remain intact
Attributes in other categories, such as Location or Demographic, are exported as they are, even if they hold personal details such as a street address.
Column structure (headers and order) is preserved — only values change

This option is intended for regulated-industry customers (finance, healthcare, insurance) who must exclude PII from data exports.

Example:

mutation exportSignalsSuppressPii {
  exportSignals(
    jobName: "Export Signals - No PII"
    export: {
      signals: {
        signalTypes: ["emailClick", "smsOpen", "whatsAppSend"]
        timestampStart: "2022-12-23T00:00:00.000Z"
        timestampEnd: "2022-12-23T00:00:00.000Z"
        suppressPiiFields: true
      }
    }
  ) {
    dataJobId
    path
    fileFormat
  }
}

Signal types

The signal types you can export depend on what's available for export in your subscription. Acoustic makes new signal types available without an API change. If you request a type that isn't available, the request fails (see Errors below). A few system types can't be exported, such as session end and behavioral attribute changes.

Behavior signals

accountRegistered - Successful account registration events
accountUpdated - Changes to a visitor's account, such as profile details, consent, password, sign-in method or a deletion request
addToCart - Adding products to the shopping cart
browseAbandonment - Browsing products or categories without adding anything to the shopping cart
cartAbandonment - Adding items to the shopping cart without completing the purchase
error - Encountering an error on the site
identification - Capture of visitors' emails or client/contact IDs
loggedIn - Successful user authentication events
onSiteSearch - Website search activity
order - Order placement
pageView - Page view events
productConfiguration - Interactions on product pages
productView - Product view events
removedFromCart - Removing products from the shopping cart
richMediaInteraction - Interactions with video and audio content
wishlistItemAdded - Adding products to a wishlist or saved-items list
wishlistItemRemoved - Removing products from a wishlist or saved-items list

Custom behavior signals: if your subscription has custom behavior signal types that are available for export, you can export them too. Pass the custom type name in signalTypes.

Marketing signals

Email:

emailClick - Email link clicks
emailDelivery - Successful email deliveries
emailFailure - Email delivery failures
emailInbound - Inbound email responses
emailOpen - Email opens
emailSend - Email send events

SMS:

smsClick - SMS link clicks
smsDelivery - Successful SMS deliveries
smsFailure - SMS delivery failures
smsInbound - Inbound SMS responses
smsSend - SMS send events

WhatsApp:

whatsAppClick - WhatsApp link clicks
whatsAppDelivery - Successful WhatsApp deliveries
whatsAppFailure - WhatsApp delivery failures
whatsAppInbound - Inbound WhatsApp responses
whatsAppOpen - WhatsApp message opens
whatsAppSend - WhatsApp send events

Mobile push:

mobileClick - Mobile push clicks
mobileDelivery - Successful mobile push deliveries
mobileFailure - Mobile push delivery failures
mobileOpen - Taps on a mobile push notification that open your app or the phone dialer
mobileSend - Mobile push send events

Consent signals

consentUpdateEmail - Changes to a contact's email consent
consentUpdateMobile - Changes to a contact's mobile push consent
consentUpdateSms - Changes to a contact's SMS consent
consentUpdateWhatsApp - Changes to a contact's WhatsApp consent

Form signals

submittedForm - Form events, such as a sign-up, an opt-in or a profile update

Notifications object

channel (required): Enum - Notification delivery channel (valid values: EMAIL)
destination (required): String - Email address for notifications

Custom file placement (optional)

The to object contains the sftp object with two approaches for file placement:

Approach 1: Using parentFolder and namingPrefix

parentFolder: String - Custom subdirectory (must start with Export/Signals)
- Allowed characters: alphanumeric, spaces, hyphens (-), underscores (_), slashes (/)
- Example: Export/Signals/Test
namingPrefix: String - String - Custom name for the export folder and file. It replaces the default name, Signals_Export.String - Custom name for the export folder and file. It replaces the default name, Signals_Export.

Each export goes into its own folder, named with the prefix and a UTC timestamp, and the file is compressed. For example, parentFolder: "Export/Signals/Portal_QA" with namingPrefix: "weekly_orders" creates Export/Signals/Portal_QA/weekly_orders_2026_10_30_012538177/weekly_orders.csv.gzip. The response's path field returns the full path.

Approach 2: Using path

Use this approach when you need full control over the file path and name.

path: String - Complete file path on SFTP server (relative to subscription directory)
- Must be unique and include the file name with the .csv extension.
- Cannot be combined with parentFolder or namingPrefix.
- Example: Behavior Signals/Order/Demo_Export.csv

Response fields

dataJobId (required): String - Export job ID (use this to track status in Connect)
fileFormat (required): String - Export file format (valid values: CSV)
path (required): String - File path on SFTP server (relative to subscription directory).

Errors

A request that fails validation still returns HTTP 200, but data is null. The error is in errors[].extensions: code is INPUT_VALIDATION_FAILED, and messages lists each problem. These errors relate to signal types:

Error	What it means
`Invalid signalTypes: <list>.`	The type doesn't exist. Check the spelling, which is case-sensitive.
`None of the requested signalTypes are exportable: <list>.`	None of the requested types is available for export in your subscription.
`The following requested signalTypes are not exportable: <list>.`	Some of the requested types aren't available for export. The whole request fails. Remove those types and try again.
`Signal export is not enabled for any signal type`	You omitted `signalTypes`, and no type is available for export in your subscription. Contact Acoustic support.

Other validation errors cover the date range (timestampEnd must be later than timestampStart, and the range can't be longer than 365 days), an empty jobName, and the SFTP path rules described under Custom file placement.

Export process workflow

Step 1: Job monitoring

Log in to Acoustic Connect.
Navigate to Data management > Job monitoring.
Find your export job on the Job status tab.

📘
Note
Processing typically takes several minutes.

Step 2: SFTP server access setup

You need this step if you haven't accessed our SFTP server before. For instructions, see Configure access to your Connect SFTP directory.

Step 3: File collection

Access files via SFTP server.

Notes:

Files are grouped by date.
Files are automatically deleted after 28 days.
You cannot delete or rename the default /Export/Signals/ directory (it's reserved for export tasks).

Export data structure

The CSV contains one row per signal. All signal families share one column list. When a column doesn't apply to a row, or the data isn't available, it's empty: for example, consent rows have no campaign columns. Columns are grouped below by the family they belong to.

Common data (all signal types)

DATASET_ID: Text - Your audience ID
SUBSCRIPTION_ID: Text - Your Connect subscription ID
TEMPORARY_LINKING_ID: Text - Temporary ID linking audience with signal data. It changes every week and stays the same only within one calendar week (Monday to Sunday, UTC). Use it to join audience and signal data within a file. To join files from different weeks, use the contact key or other audience attributes.

Behavior signal data

ACOUSTIC_APP_KEY: Text - Your application identifier in Connect
CATEGORY: Text - Signal category (valid values: Behavior, Marketing)
DESCRIPTION: Text - Signal description
NAME: Text - Signal name
OBSERVED_TIMESTAMP: DateTime text - When Connect processed signal making it available for analytics (UTC, ISO 8601) - Example: 2025-08-31T08:29:30.001Z
RECEIVED_TIMESTAMP: DateTime text - When Connect received signal (UTC, ISO 8601) - Example: 2025-08-31T08:29:30.001Z
SIGNAL_CONTENT: JSON - Raw signal content containing the complete signal payload with all signal-specific fields (for details on signal-specific field structures, see Enable real-time import of behavior signals to Connect).
Signal-specific attributes: Various - one column per attribute in the signal content, named
SIGNAL_GROUP: Text - Signal grouping identifier (valid values: session, page, order, cart, product)
SIGNAL_TIMESTAMP: DateTime text - When signal happened (UTC, ISO 8601) - Example: 2025-08-31T08:29:30.001Z
SCREEN_VIEW_NAME: Text - Most recent screen view when a behavior signal happens
TLTSID: Text - The UUID portion of the session ID (generated by the Connect library)

Click fields on behavior rows: behavior rows don't have their own SIGNAL_ID. If the visitor arrived by clicking a link in a message, SIGNAL_ID, MESSAGE_ID, CAMPAIGN_ID, LINK_ID and TIMESTAMP on the behavior row hold the values of that click. Otherwise, these columns are empty. See Link website signals to message clicks below.

Marketing signal data

Signal metadata

BOT_DETECTED: Boolean - Whether click was detected as bot traffic
BOT_DETECTION_REASON: Text - Reason for bot classification (valid values: APPLE_MPP, DELIVERY_OPEN_THRESHOLD, OPEN_COUNT_THRESHOLD, CLICK_COUNT_THRESHOLD, OPEN_CLICK_THRESHOLD, CLICK_TIME_THRESHOLD, USER_AGENT)
CLASSIFICATION: Text - Type of inbound message or failure (valid values: PERMANENT, TEMPORARY, UNSUBSCRIBE, ABUSE, CHANGE_OF_ADDRESS, DOI_CONFIRM, OTHER)
CLASSIFICATION_CODE: Text - Additional classification detail (valid values: BAD_CONTENT, BAD_RECIPIENT, BAD_RELAY, BAD_SENDER, OTHER, RESTRICTION, SYSTEM)
SIGNAL_ID: Text - Unique signal identifier
- On marketing rows and consent rows, it's the signal's own ID.
- On behavior rows, it's the ID of the message click that led to the behavior, or empty (see Click fields on behavior rows).
- Form rows have no SIGNAL_ID.
SIGNAL_TYPE: Text - Type of signal (see Signal types above)
TIMESTAMP: DateTime text - When signal was received (UTC, ISO 8601)
- On marketing rows, use this column. SIGNAL_TIMESTAMP, RECEIVED_TIMESTAMP and OBSERVED_TIMESTAMP are empty.
- On behavior rows, it's the time of the linked click.
- It's empty on consent rows.

Contact data

Addressable attributes: Text - Separate column for each addressable contact attribute (email, phone)
CONSENT_EMAIL: Text - The contact's current email consent (valid values: yes, no, never)
CONSENT_SMS: Text - The contact's current SMS consent (valid values: yes, no, never)
CONSENT_WHATSAPP: Text - The contact's current WhatsApp consent (valid values: yes, no, never)
CONSENT_MOBILE: Text - The contact's current mobile push consent (valid values: yes, no, never)
Non-addressable attributes: Various - All other audience attributes including Contact key

yes means the contact opted in, no means they opted out, and never means no consent was ever recorded for that channel.

Contact data columns appear on marketing, behavior, consent and form rows when the signal is linked to a contact.

Campaign data

CAMPAIGN_DESCRIPTION: Text - User-defined description of the marketing campaign that the message originates from
CAMPAIGN_ID: Text - Unique identifier of the marketing campaign that the message originates from
CAMPAIGN_NAME: Text - Campaign name
CAMPAIGN_STATUS: Text - Current campaign status
- RUNNING: Active campaign mailings
- COMPLETED: Completed campaign mailings
- CANCELLED: Canceled campaign mailings
- TEMPLATE: Mailings that use content retrieval
CAMPAIGN_TYPE: Text - Campaign type (valid values: SCHEDULED, TRIGGERED, MULTISTEP)
COMPLETED_DATE: DateTime text - Campaign completion date (ISO 8601)
CONSENT_GROUP_ID: Text - Consent group ID used for the send
ENTRY_SIGNAL: Text - Signal used as entrance criteria for triggered/multistep campaigns
ENTRY_TYPE: Text - How contacts enter campaign (valid values: SEGMENT, SIGNAL)
FREQUENCY: Text - Campaign frequency (valid values: ALWAYS ON, ONE TIME)
SCHEDULED_DATE: DateTime text - Campaign scheduled/start date (ISO 8601)
SEGMENT_DEFINITION_ID: Text - Segment definition ID
SEGMENT_ID: Text - Segment ID for scheduled campaigns
TAGS: Array of text - Campaign tags

Message data

Core message fields:

MESSAGE_ID: Text - Published message ID
MESSAGE_NAME: Text - Message name
MESSAGE_TAGS: Array of text - Message tags

Link data:

LINK_ID: Text - Clicked link ID

Personalization data:

AUDIENCE_VARIABLES: Array of text - Variables from audience data
PERSONALIZATION_VARIABLES: Array of text - All variable datasets used for personalization
PLACEHOLDER_VARIABLES: Array of text - Variables included in message
PRODUCT_VARIABLES: Array of text - Variables from product catalog
REFERENCE_SET_VARIABLES: Array of text - Variables from reference set

Email-specific fields:

EMAIL_FROM_ADDRESS: Text - Sender email address
EMAIL_FROM_NAME: Text - Sender display name
EMAIL_PRE_HEADER: Text - Preview text after subject line
EMAIL_REPLY_TO_ADDRESS: Text - Reply-to address
EMAIL_SUBJECT: Text - Email subject line
EMAIL_TAGS: Array of text - Email-specific tags
EMAIL_TRACKING_LEVEL: Text - Tracking level (valid values: no_tracking, aggregate, unique, opens_only)
VMTA: Text - VirtualMTA selected for message
VMTA_POOL: Text - VMTA pool for mailing

SMS-specific fields:

INCLUDES_MEDIA: Boolean - Whether SMS includes media
IS_MMS: Boolean - Whether SMS includes media content (making it MMS)
SMS_TAGS: Array of text - SMS-specific tags

WhatsApp-specific fields

INCLUDES_MEDIA: Boolean - Whether WhatsApp message includes media
WHATSAPP_MESSAGE_BODY: Text - Non-personalized message body
WHATSAPP_TAGS: Array of text - WhatsApp-specific tags
WHATSAPP_TEMPLATE_CATEGORY: Text - Template category (valid values: Marketing, One-time password, Transactional)
WHATSAPP_TEMPLATE_ID: Text - Template ID
WHATSAPP_TEMPLATE_NAME: Text - Template name
WHATSAPP_TYPE: Text - Message type (valid values: Custom, Templated)

Consent signal data

Rows for consentUpdateEmail, consentUpdateMobile, consentUpdateSms and consentUpdateWhatsApp:

CHANNEL: Text - Channel the consent applies to (valid values: EMAIL, SMS, WHATSAPP, MOBILE)
CONSENT_GROUP_ID: Text - Consent group the change applies to
OBSERVED_TIMESTAMP: DateTime text - When Connect processed the signal (UTC, ISO 8601)
OPERATION_SOURCE: Text - Where the change came from, for example ac-api-audience
RECEIVED_TIMESTAMP: DateTime text - When Connect received the signal (UTC, ISO 8601)
SIGNAL_CATEGORY: Text - Signal category, for example consent
SIGNAL_ID: Text - Unique ID of the consent change
SIGNAL_TIMESTAMP: DateTime text - When the consent change happened (UTC, ISO 8601)
SIGNAL_TYPE: Text - Consent signal type
STATUS: Text - New consent status (valid values: OPT_IN, OPT_OUT, OPT_IN_UNVERIFIED)

Consent rows also include SUBSCRIPTION_ID, TEMPORARY_LINKING_ID and the contact data columns.

Note:
CHANNEL and STATUS describe the change in this signal. The CONSENT_EMAIL, CONSENT_SMS, CONSENT_WHATSAPP and CONSENT_MOBILE contact columns show the contact's current consent.

Form signal data

Rows for submittedForm:

EVENT_CATEGORY: Text - Category of the form event, for example formSubmission
EVENT_TYPE: Text - Type of form event, for example OPT_IN or UPDATE
FORM_ID: Text - ID of the form
OBSERVED_TIMESTAMP: DateTime text - When Connect processed the signal (UTC, ISO 8601)
RECEIVED_TIMESTAMP: DateTime text - When Connect received the signal (UTC, ISO 8601)
SIGNAL_TIMESTAMP: DateTime text - When the form event happened (UTC, ISO 8601)
SIGNAL_TYPE: Text - submittedForm
TIMESTAMP: DateTime text - When the form event happened (UTC, ISO 8601). Same value as SIGNAL_TIMESTAMP

Form rows also include SUBSCRIPTION_ID, TEMPORARY_LINKING_ID and the contact data columns. Form signals use EVENT_TYPE and EVENT_CATEGORY where consent signals use SIGNAL_CATEGORY.

Link website signals to message clicks

To see which message click led to an order or other website activity, link the behavior row to the click row.

In the same export, request the behavior types (for example order) together with the click types (emailClick, smsClick, whatsAppClick). An export with only click signals has no behavior rows to link.
Join the behavior row to the click row on SIGNAL_ID.
A click can happen days before the order. Join against click data from earlier days too, by widening the date range or using earlier export files.

Requirements:

Web Tracking is enabled for the clicked link.
The behavior happens in the same browsing session that started from the click.
If your site redirects across domains (for example from .net to .com), the redirect keeps the ace URL parameter.

Consent and form rows can't be linked to a message click.

Example usage

Export all SMS signals (using path)

mutation {
  exportSignals(
    jobName: "SMS Signals - Q3 2025"
    export: {
      signals: {
        signalTypes: ["smsSend", "smsDelivery", "smsFailure", "smsClick"]
        timestampStart: "2025-07-01T00:00:00.000Z"
        timestampEnd: "2025-09-30T23:59:59.999Z"
      }
    }
    to: {
      sftp: {
        path: "SMS_Reports/Q3_2025/SMS_Signals_Export.csv"
      }
    }
  ) {
    dataJobId
    path
    fileFormat
  }
}

Export shopping funnel signals (using parentFolder + namingPrefix)

mutation {
  exportSignals(
    jobName: "Shopping Funnel Analysis - August 2025"
    export: {
      signals: {
        signalTypes: [
          "addToCart"
          "cartAbandonment"
          "browseAbandonment"
          "order"
          "removedFromCart"
        ]
        timestampStart: "2025-12-01T00:00:00.000Z"
        timestampEnd: "2025-12-31T23:59:59.999Z"
      }
    }
    to: {
      sftp: {
        parentFolder: "Export/Signals/Shopping_Funnel"
        namingPrefix: "December_2025_"
      }
    }
    notifications: [{ channel: EMAIL, destination: "[email protected]" }]
  ) {
    dataJobId
    path
    fileFormat
  }
}

Export product engagement signals (using path)

mutation {
  exportSignals(
    jobName: "Product Engagement Q3 2025"
    export: {
      signals: {
        signalTypes: ["productView", "productConfiguration", "richMediaInteraction", "onSiteSearch"]
        timestampStart: "2025-07-01T00:00:00.000Z"
        timestampEnd: "2025-09-30T23:59:59.999Z"
      }
    }
    to: {
      sftp: {
        path: "Behavior_Signals/Product_Engagement/Q3_2025_Export.csv"
      }
    }
  ) {
    dataJobId
    path
    fileFormat
  }
}

Export consent changes for an audit (using parentFolder + namingPrefix)

mutation {
  exportSignals(
    jobName: "Consent audit - Q3 2026"
    export: {
      signals: {
        signalTypes: [
          "consentUpdateEmail"
          "consentUpdateSms"
          "consentUpdateWhatsApp"
          "consentUpdateMobile"
        ]
        timestampStart: "2026-07-01T00:00:00.000Z"
        timestampEnd: "2026-09-30T23:59:59.999Z"
      }
    }
    to: {
      sftp: {
        parentFolder: "Export/Signals/Consent_Audit"
        namingPrefix: "Q3_2026_consent"
      }
    }
  ) {
    dataJobId
    path
    fileFormat
  }
}