Import behavior signals in bulk via SFTP

Acoustic Connect can bulk-import behavior signals from a file already staged on your Acoustic SFTP server, processing many historical or batched signals in a single job. Use this method instead of createSignals when you need to backfill historical data or move signals captured outside Connect's real-time tracking — for example, a data pipeline that exports nightly behavior logs.

Requirements

Signal limits

Your Connect subscription determines which signal types you can import. The same catalog and tier restrictions apply as for real-time import:

Contact mapping

Each signal must map to a contact. Use identifiableAttributes to provide a contact key, an addressable attribute (email, sms, or whatsapp), or several together — for example, a contact key and an email address in the same signal.

Connect processes identification records in this order:

• An existing contact key match maps the signal to that contact and updates it if the signal includes changes.

• A new key paired with an addressable attribute that matches an existing contact either assigns the key to that contact (if it has none yet) or creates a new contact (if the matched contact already has a different key — keys are permanent and can't be overwritten).

• A new key paired with a new addressable attribute creates a new contact.

• A contact key alone — with no addressable attribute and no match to an existing contact — doesn't link to any contact. The signal is still processed and appears in Signal management.

  
  See How signals update data in your Connect subscription for the full processing logic.

File format

• Format: JSONL only — each line is one standalone signal JSON object. fileFormat: DELIMITED is not applicable to signals imports.
• Maximum file size: 500 MB.
• The file is removed from the SFTP folder once a job successfully processes it. If a file is never processed, it's automatically removed 14 days after upload.

Before you begin

Obtain your application key, which maps imported signals to an application:

• Connect Pro: Key provided during onboarding
• Connect Premium and Ultimate: Generated through Connect interface, see Get an application key for the Connect library)

Confirm you have:

• Access to the Acoustic SFTP server, configured via SSH key, see Configure access to the Connect SFTP server
• A properly formatted JSONL file, already uploaded to your subscription's SFTP folder

The file must exist on the SFTP server before you call createImportJob. The mutation starts a job against a file that's already there — it does not accept or upload file content itself.

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.

mutation CreateImportJob($importInput: ImportInput!) {
  createImportJob(importInput: $importInput) {
    id
  }
}

Example

{
  "importInput": {
    "importType": "ADD_UPDATE",
    "into": "SIGNALS",
    "fileFormat": "JSONL",
    "skipFirstRow": false,
    "jobName": "SignalsImportJob_<uuid>",
    "fileLocation": {
      "type": "SFTP",
      "folder": "automation",
      "filename": "signals.jsonl"
    }
  }
}

Mutation arguments

importInput (required): Object — see fields below.

ImportInput fields for a signals import

• importType (required): Enum — ADD_UPDATE is the value used for signals imports.
  

  📘

  Caution:

  Use ADD_UPDATE only. If your GraphQL client's autocomplete or schema explorer shows CREATE or DELETE as other ImportType options, don't use them for signals imports — CREATE is rejected with a validation error, and DELETE is silently ignored: the job reports success, but records are added/updated exactly as with ADD_UPDATE, not deleted.

• into (required): Enum — SIGNALS.
• fileFormat (required): Enum — JSONL.
• jobName (required): String — a name for the import job. Convention: SignalsImportJob_<uuid>.
• fileLocation (required): Object —
  • type (required): Enum — SFTP.
  • folder (required for SFTP): String — the folder path containing the file, relative to your subscription's own SFTP root. Do not include the subscription-name folder that SFTP clients show as the top-level directory after connecting.
  • filename (required for SFTP): String — the filename only, excluding the folder.
• notifications: Array of objects — optional; omit to send no notifications.
  • channel (required): Enum — valid value: EMAIL.
  • destination (required): String — where to send notifications.
    On job completion, an email arrives from The Connect Team ([email protected]), subject "Import job completed successfully -
• skipFirstRow: Boolean (default false) — not meaningful for fileFormat: JSONL; applies only to DELIMITED files.

Signal file object (one per line in the JSONL file)

• appKey (required): String — your application identifier in Connect.
• identifiableAttributes (required): Object — one contact identifier as a key-value pair. Valid keys: contactKey, email, sms, whatsapp.
• sessionId: String — optional; groups signals from the same contact session. See Session ID behavior below.
• signalContent (required): JSON object — the signal data specific to each signal type. See the Real-time signal import reference for the field breakdown per signal type — the same signalContent shapes apply here.
• test: Boolean (default false) — optional; flag for test signals.

{
  "signal": {
    "appKey": "YOUR_APP_KEY",
    "identifiableAttributes": {
      "email": "[email protected]"
    },
    "sessionId": "SESS-789456123AB",
    "signalContent": {
      "signalType": "addToCart"
    },
    "test": false
  }
}

Response fields

The mutation returns a JSON response containing:

• data: Object — root data object containing mutation results
  • createImportJob: Object — result of the import job creation
    • id: String — the import job identifier. Use this to track progress in Job monitoring.

Verification methods

Method 1: Check job status

1. Go to Administration > Job monitoring.
2. Select the Job status tab.
3. Find the job by name and track its progress.

Method 2: Review contact activity

1. Go to Audience > Contacts.
2. On the All contacts tab, select a contact associated with the imported signals.
3. Check the activity feed for the signals.

Notes:

• Activity feed shows the 5 most recent signals per session (identification signals aren't displayed).
• Displays the last 1,000 signals or signals from the last 30 days, sorted by signal timestamp.
• Newly imported signals may not be immediately visible — wait a few minutes and refresh.

Method 3: Signal management

Go to Behavior studio > Signal management and select a signal type to confirm imported signals appear in the list.

How it works

Required vs. optional fields

If any required field in a signal line is missing or invalid, that entire signal is discarded — the rest of the file continues processing independently. Optional fields enhance a signal but don't prevent processing if omitted.

File and job requirements

• The file must already exist in the specified SFTP folder before createImportJob is called.
• The file is removed from the SFTP folder once a job successfully processes it. Re-running createImportJob against the same filename after a successful job will fail, because the file is no longer there — upload a fresh copy (a new filename, or the same name re-uploaded) if you need to reprocess the same data.
• If a file is never processed, it's automatically removed from the SFTP server 14 days after upload.
• Maximum file size is 500 MB.

Test signals

When test is set to true:

• Signals undergo standard validation.
• They have no impact on campaigns.
• They aren't visible in the Activity feed, Segmentation, or Insights.

Session ID behavior

When you provide a sessionId:

• The system registers the session as if it was generated by the Connect library.
• Signals are included in aggregate reports and in-market interest calculations.

When you omit sessionId:

• Signals appear in contacts' activity feeds.
• Signals aren't used for aggregate reports or behavioral intelligence calculations.

Related pages

• Enable real-time import of behavior signals to Connect
• Import behavior signals from local storage
• Import behavior signals from SFTP
• Send signals from a backend system
• Configure access to the Connect SFTP server
• Using the Connect API